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Styles : keyword function/method type replaced_expression 
variable literal module module filename language_syntax 
Notatioris : 

f (... ) -> return value f (... ) > return nothing (procedure) 

[x] for a list of x data, (x) for a tupie ofxdata, may have x{n}-> 
n times x data. 

Environment Variables 


PYTHONCASEOK 

PYTHONDEBUG 

PYTHONHOME 

PYTHON INSPECT 
PYTHONOPTIMIZE 

PYTHONPATH 


PYTHONSTARTUP 
PYTHON UNBUFFERE 
D 

PYTHONVERBOSE 
1 If set to non-empty 


1 no case distinction in module->file mapping 
1 = -d command-line option 
Modify Standard Python libs prefix and exec 
prefix locations. Use <prefix>[:<execprefix>]. 

1 = -i command-line option 
1 = -O command-line option 
Directories where Python search when 
importing modules/packages. Separator : 
(posix) or ; (Windows). Under Windows use 
registry HKLM\Sofware\.... 

File to load at begining of Interactive sessions. 
1 = -u command-line option 

1 = -v command-line option 
value. 


Command-line Options 


python [-dEhiOQStuUvVWx] [-c cmd -m mod | file \ -] [args ] 

-d Output debugging infos from parser. 

-E Ignore environment variables. 

-h Print help and exit. 

-i Force interactive mode with prompt (even after script 

execution). 

-O Optimize generated bytecode, remove assert checks. 

-OO As -O and remove documentation strings. 

-Q arg Division option, arg in [old(default),warn,warnall,new]. 

-S Don't import site.py definitions module. 

-t Warn inconsistent tab/space usage (-tt exit with error). 

-u Use unbuffered binary output for stdout and stderr. 

-U Force use of Unicode literals for strings. 

-v Trace imports. 

-V Print version number and exit. 

-W arg Emit warning for arg 

"action:message:category: module: lineno" 

-x Skip first line of source (fort non-Unix forms of #!cmd). 

-c cmd Execute cmd. 

-m mod Search module mod in sys.path and runs it as main script. 
file Python script file to execute. 

args Command-line arguments for cmd/file, available in 
sys . argv [1:]. 


Types 

basestring 1 bool buffer complex dict exception file float 
frozenset int list long object set slice str tupie type 
Unicode xrange 

1 basestring is Virtual superclass of str and Unicode. 

This doc uses string when Unicode and str can apply. 

Functions 

Constructor functions of builtin types are directly accessible in 
builtins. 

_import_ abs apply 1 callable chr classmethod cmp coerce 

compile delattr dir divmod enumerate eval execfile 
filter getattr globals hasattr hash help hex id input 
intern 2 isinstance issubclass iter len locals map max min 
oct open ord pow property range raw_input reduce reload 
repr reversed round setattr sorted staticmethod sum 
super unichr vars zip 

1 Use f(*args,**kargs) in place of apply(f,args,kargs). 

2 Don't use intern. 

Statements 

One statement per line 1 . Can continue on next line if an expression 
or a string is not finished not closed), or with a \ at 

end of line. 

Char # start comments up to end of line. 


pass 

assert expr[ ,message] 
dei namel,...] 
print (»ob/.1(expr[....lf,] 
exec expr [in globals [, 
locals ]] 

fct(\expr \,...)], 

\name=expr [,...)) 

[, *args][, **kwargs]) 
namel,.,.,.] = expr 


Null statement. 

Assertion check expression true. 
Remove name -> object binding. 

Write expr to sys . stdout 2 . 

Execute expr in namespaces. 

Call any callable object fct with given 
arguments (see Functions Definitions 
& Usage - p2). 

Assignment operator 3 . 


1 Multiple statements on same line using ; separator - avoid if not 
necessary. 

2 Write to any specified object following file interface (write 
method). 

Write space between expressions, line-return at end of line except 
with a final ,. 

3 Left part name can be Container expression. If expr is a sequence 
of multiple values, can unpack into multiple names. Can have 
multiple assignments of same value on same line : a = b = c = 
expr. 

Other statements (loops, conditions...) introduced in respective 
parts. 


Blocks 


Files Extensions 

.py=source, . pyc=bytecode, ,pyo=bytecode optimized, ,pyd=binary 
module, .dll/.so=dynamic library. 

I .pyw=source associated to pythonw.exe on Windows platform, to 
| run without opening a console. 

Language Keywords 

| List of keywords in Standard module keyword 
and as 1 assert break class continue def dei elif else 
except exec finally for from global if import in is 
lambda not or pass print raise return try while yield 
I 1 not reserved, but avoid to redefine it. 

| Don't redefine these constants : None, True, False. 

Builtins 

Available directly everywhere with no specific import. Defined also 
in module builtins 


A : between statements defines dependant statements, written on 
same line or written on following line(s) with deeper indentation. 
Blocks of statements are simply lines at same indentation level. 

if x<=0 : return 1 
if asin(v)>pi/4 : 
a - pi/2 
b = -pi/2 
else : 

a = asin(v) 
b = pi/2-a 

Statement continuation lines don't care indentation. 

To avoid problems, configure your editor to use 4 spaces in place 
of tabs. 

Assignment Shortcuts 

a += b a -= b a *= b a /= b 

a //= b a %= b a **= b 

a s= b a |= b a A = b a »= b a «= b 

Evaluate a once, and assign to a the resuit of operator before = 


Ia 


1b 


1 c 





















































































































































applied to current a and b. Example : ai=b ~ a=aib 

Console & Interactive Input/Output 

print expression i 

input ([prompt]) -» evaluation of user input (typed data) 
raw_input ([prompt]) -> str: user input as a raw string 
Direct manipulation (redefinition) of stdin/stdout/stderr via sys 
module : 

sys.stdin sys.stdout sys.stderr 

sys. stdin sys. stdout sys. stderr 

I AII are files or files-like objects. The_xxx_forms keep access to 

| original Standard 10 streams. 

Ctrl-C raises Keyboardlnterrupt exception. 

_ -> value of last expression evaluation 

help ([ob/ect]) ► print Online documentation 

sys . displayhook -> (rw) fct(value) called to display value 

sys. _displayhook_ -> backup of original displayhook function 

sys .psl -> str: primary interpreter prompt 

sys ,ps2 -> str: secondary (continuation) interpreter prompt 

See external package ipython for an enhanced interactive Python 
shell. 

Objects, Names and Namespaces 
Identifiers 

Use : [a-zA-Z_][a-zA-Z0-9J* 

Special usage for underscore : 

_xxx global not imported by import * 
xxx implementation detail, for internal use (good 
practice) 

_xxx 'private' class members, defined as 

_ClassName_xxx 

_ xxx _ normally reserved by Python 

Case is significant : This_Name != this_name. 

Objects and Names, Reference Counting 

Data are typed objects (ali data), names are dynamically bound to 
objects. 

= assignment statement bind resuit of right part evaluation into left 
part name(s)/container(s). Examples : 

a = 3*c+5 a,b = ("Helio","World") x,y,tabz[i] = fct(i) 
s - "Helio" pi,e - 3.14,2.71 a,b - b,a 

When an object is no longer referenced (by names or by 
containers), it is destroyed (its _dei_ method is then called). 

sys.getrefcount (object) -> int: current reference counter of object 

Standard module weakref define tools to allow objects to be 
garbage collected when necessary and dynamically re-created on- 
demand. 

Mutable/lmmutable Objects 

Mutable objects can be modified in place. Immutable objects cannot 
be modified (must build a new object with new value). 

Immutable : bool, int, long, float, complex, string, Unicode, 
tuple, frozenset, buffer, slice. 

Mutable : list, set, dict and other high level class objects. 

There is no constant definition. Just use uppercase names to identify 
symbols which must not be modified. 

Namespaces 

Places where Python found names. 

Builtins namespace -> names from module _builtins_ , already 

available. 

Global namespace -» names defined at module level (zero 
indentation). 

Local namespace -» names defined in methods/functions. 
dei name > remove existing name from namespace (remove object 
binding) 


globals () -> dict: identifier->value of global namespace 

locals () -> dict: identifier->value of local namespace 

Current scope -> names directly usable. Searched in locals, then 
locals from enclosing definitions, then globals, then builtins. 

Out-of-scope name -» use the dotted attribute notation x.y (maybe 
x.y.z.t)... where x is a name visible within the current scope. 

Class namespace -» names defined in a class (class members). 

Object namespace -> names usable with object.name notation 
(attributes, methods). 

Namespaces can be nested, inner namespaces hidding identical 
names from outer namespaces. 

dir {[object]) -> list: names defined in object namespace 1 

vars ([object]) -> dict 2 : identifier:value of object as a namespace 1 

I 1 if object not specified use nearest namespace (locals). 

| 2 must not be modified. 

Constants, Enumerations 

Use uppercase and _for constants identifiers (good practice). May 
define namespaces to group constants. Cannot avoid global/local 
name redefinition (can eventually define namespaces as classes 
with attributes access control - not in Python spirit, and execution 
cost). 

See third party modules pyenum for striet enum-like namespace. 

Flow Control 


Loop 

for var|,...] in iterable : inst 
[ else : inst ] 

while cond : inst 
[ else : inst ] 

Exit loop with break. 

Go to next iteration with continue. 

Loops else blocs only exeeuted when 
loop exit normally (without break). 

Functions/methods exit 

Exit function/method with return [value] 

Exit from generator body with yield value 

I Multiple returned values using tuple data. 

| Cannot yield within a try/finally block. 

Exceptions 

try : inst 

excegt .[ exceptjclass [, value ]] : inst 
[ else : inst ] 

Can have a tuple of classes for except_class. Not specifying a class 
catch all exceptions. 

Block else exeeuted when try block exit normally. 
try : inst 
finally : inst 

| Process finally block in all execution paths (normal or exception). 
raise exception_class [, value[, traceback]] 
raise exception_object 

raise 

I Last form re-raise the currently catched exception in an exception 
| handler. 

Iterable Protocol 

Generic and simple protocol allowing to iterate on any collection of 
data. 

Objects of class defining_ iter_ or_ getitem_ are iterable 

(directly usable in for loops). 

_iter_ (self) -> iterator on self 

iter ( object ) -> iterator on iterable object 


iter (callable ,sentinel) -» iterator returning callableO values up to 
sentinel 

enumerate ( iterable ) -»iterator returning tuples (index,value) from iterable 
Iterators Objects Interface 
next (self)-* next item 1 
_iter_ (self)-* iterator object itself 

F^When reach end of collection, raise stopiteration exception on 
subsequent calls (ie. iterator usable only one time on a collection). 
Generators 

Functions retaining their state between two calls. Return values 
using yield. Stop generation via simple return or via raise 

Stopiteration. 

1) build generator from function : gen=generatorfct (args) 

2) use gen. next() values until stopiteration is raised. 

Generator iterable expressions with : (x for x in iterable where 

cond) 

Operations with/on Iterable 
See Operations on Containers (p8). 

See Iteration Tools (p9). 

Interpretation / Execution 

compile (string 1 ,filename ,kind 2 [ ,flags 3 [ ,dont_inherit 3 ]]) -» code object 
eval (expressioni ,globals[,locals]]) -> value: evaluation 4 of expression 
string 

eval (code_object[ ,globals[,locals]]) -> value: evaluation 4 of code_object 
exee 5 statements [in globals],locals]] > statements string 1 exeeuted 4 
exeef ile (filename[ ,globals[,locals]]) > file filename interpreted 4 

1 Multi-line statements in source code must use \n as newline, and 
must be terminated by a newline. 

2 Kind relative to string content, 'exee' -> sequence of statements, 
'eval' -> single expression, 'single' -> single interactive 
statement. 

3 Flags and dontjnherit are for future statements (see doc). 

4 In context of globals and locals namespaces. 

5 Exee is a langage statement, others are builtin functions. 

Functions Definitions & Usage 

def fetname (lparamname[r=defaultvalue]l ,...[] [, *args][, **kwargs]) : 
instructions 

new. function (code,globals[ ,name[ ,argdefs]]) -> python function (see 
docs) 

Parameters / Return value 

Parameters are passed by references to objects. 

You can modify values of mutable objects types. 

You cannot modify values of immutable objects types - as if they 
were passed by value. 

Notation * -> variable list of anonymous parameters in a tuple. 
Notation ** -> variable list of named parameters in a dict. 

Return value(s) with return [value 

For multiple values, return a tuple. If no return value specified or if 
end of function definition reached, return None value. 

Lambda functions 

lambda param[, : expression 

Anonymous functions defined inline. Resuit of expression evaluation 
is returned (it must be an expression, no loop, no condition). 

Expression uses values known at definition time (except for 
params). 

Callable Objects 

Objects having a _ call _ method can be used as functions. 

Methods bound to objects can be used as functions : f = o.meth 
callable (x) -> bool: test x callable with x(...) 


Condition 

if cond : inst 
[ elif cond : inst ] 

[ else : inst ] 

There is no 'switch' or 
'case'. 

Can use if elif elif... else. 
Can use a mapping with 
functions bound to cases. 
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Calling Functions 

[name=] fctname ([expr [,...]][ ,name=expr {,, *args][, **args ]) 
Anonymous parameters passed in parameters order declaration. 
Params having default value can be omitted. 

Notation * -> pass variable list of anonymous parameters in a 

tuple. 

Notation ** -> pass variable list of named parameters in a dict. 

Functions Control 

sys. getrecursionlimit () -* int: current recursion limit for functions 
sys. setrecursionlimit (limit) > set recursion limit for functions 

Decorators 

Glue code (functions) called at functions and methods definitions 
time, return the final function/method (generally with wrapping 
code). 

Sdecoratorname [ (decorator_arguments)l i...] 
def fct (fctjguments) :... 

@decl Sdec2 (args) @cfec3 def fct (...) :... 

def fct(...) :... like fct = decl (dec2(args) (dec3 (fct )))) 

► 

I See page PythonDecoratorLibrary in python.org Wiki for some 
| decorators definitions. 

Types/Classes & Objects 

AII data are typed objects relying to classes, 
type (o) -> type: type object of o 

Standard module types define type objects for builtins types. 

Class Definition 

ciass classname [ (parentciass] ,...|) ] : 

varname = expr > varname defined in classname namespace 
def metname (selfj ,...]) : >• define methods like functions 
Support multiple inheritance. Can inherit from builtin class. 

Inherit at least from object base class => Python 'new style class'. 
First parameter of methods is target object, Standard use self 
name. 

Access class members via class name, object members via self. 

| This doc consider you use new style class (inheriting from object). 

new. classobj (name , baseclasses, dict) -> new class (see docs) 
new.instancemethod (fct,instance,ciass) -» new method: bound to 
instance it it is not None, see docs 
Metaclass 

Class definition create a new type. It can be done 'by hand' with : 
x = type ( 'classname', (parentciass, [,,,]) , { varname: expr [,...]} 
def metname ( self[ ,...]) : 
x. metname = metname 

This allow creation of metaclass class (class building other class). 

Object Creation 
obj = ClassName (initargs...) 

I In case of exception during initialization, object is destroyed when 
| exiting init code (reference counter reach zero). 

new. instance (class[, dict]) -> object: create new class instance without 

calling_ init_ method, dict is initial object attributes 

Classes & Objects Relations 
isinstance (obj,classinfo) -> bool: test object kind of type/class 
classinfo 

issubclass (aclass,aparent) -> bool: test same class or parent 
relationship 

| Prefer isinstanceQ to type() for type checking. 

Parent class methods are not automatically called if overriden in 
subclass - they must be explicitly called if necessary. 

Call parent methods via super function : 

super ( ThisClass , self ) . methodname (self, args ...) 

Or the old way, via parent class namespace : 

Parentciass. methodname ( self , args...) 
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Attributes Manipulation 

object. name = value 

setattr (object , name, value) ► object attribute set to value 
object. name -> value of object attribute 
getattr (object,name[,default]) -> value of object attribute 
dei object. name 

delattr (object,name) *■ object attribute removed 

Special Methods 

I Other special overridable_xxx_methods are listed in respective 

| sections. 

Object Life 

_new_ (classref , initargs...) -* object of classref type, already 

initialized 1 

_init_ (self ,initargs...) > called to initialize object with initargs 

_dei_ (self) >■ called when object will be destroyed 

I 1 If don't return a classref object, then object._init_is called with 

| initargs. 

Object Cast 

_repr (self )-> str: called for repr (self) and 'self' 

_str_ (self) -> str: called for str (self) and print self 

_coerce_ (self ,other) -> value, called for coerce (self , other) 

Object Hash Key 

_hash_ (self) -> int: 32 bits hash code for object, used for 

hash (obj) and quick dict mapping keys comparison - default 
implementation use hash(id(self) ) 

Attributes access 

| See also "Descriptors protocol" infra. 

_getattr_(self, name) -> value, called for undefined attributes 

_getattribute_(self, name) -> value, always called 

_setattr (self, name, value) *■ called for obj.name=vatue 

_delattr (self, name) *■ called for dei obj .name 

_call_ (self, *args, **kwargs)-> value, called for obj(...) 

Static method / Class method 
Use Standard decorators (see Decorators p3). 
class ClassName : 

@staticmethod 

def methodname (...) : ... 

@c lassmethod 

def methodname (classref ,...) : ... 

Descriptors protocol 

Descriptors are attribute objects controling access to attributes 
values. They must define some of following methods : 

_get (self ,obj,ownerclass) -> attribute value for obj 

_set (self , obj,value) *■ modify attribute in obj, setto value 

_delete_ (self , obj) y remove attribute from obj 

In these methods self is the descriptor object, and obj is the target 
object which attribute is manipulated. 

Properties 

A descriptor to directly bind methods/functions to control attribute 
access. Use builtin type property with init args. 
class MyClass : 

attributename = property (getter, setter, deleter, description) 

| Each init arg default to None (ie. undefined). 

Copying Objects 

Assignment only duplicate references. To shallow copy an object 
(build a new one with same values - referencing same content), or 
to deep copy an object (deep-copying referenced content), see 
object copy methods, and functions in Standard module copy. 
copy . copy (object) -> value: shallow copy of object 
copy . deepcopy (object[[,memo],_nil ])-> value: deep copy of object 1 
| 1 Params memo and nil are used in recursive deepcopy, their 
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default values are None and empty list. 

Copy Protocol 

_copy_ (self)-* value: shallow copy of self, called by 

copy. copy (...) 

_deepcopy_ (self , memo) -> value: deep copy of self, called by 

copy. deepcopy (...) 

For copying, objects can define pickling protocol too (see Files - 
Serialization - pl2), in place of _ copy _ and deepcopy _. 

Introspection 

Beyond this documentation. Many_ xxx _ attributes are defined, 

some are writable (see other docs). 

See Standard module inspect to manipulate these data. 

Example of Introspection Attributes 
Note: classes are objects too! 

_base_ -> list: parent classes of a class 

_slots_ -»tuple: allowed objects attributes namesl of a class 

_class_ -> class/type: objecfs class 

_dict_ -> dict: defined attributes (object namespace) of an instance 

_doc_ -> string: documentation string of a package, module, class, 

function 

_name_ -> str: object definition name of a function 

_file_ -> string: pathname of loaded module .pyc, .pyo or .pyd 

f 1 List of allowed attributes names. Usage discouraged. 

Modules and Packages 

File gabuzo.py >■ module gabuzo. 

Directory kramed/ with a file_ init_.py > package kramed. 

Can have sub-packages (subdirectories having_ init_.py file). 

Searched in the Python PATH. 

Current Python PATFI stored in sys.path list. Contains directories 
and ,zip files paths. Builtfrom location of Standard Python modules, 
pythonpath environment variable, directory of main module given 
on command line, data specified in lines of .pth files found in Python 
horne directory, and data specified in registry under Windows. 
Current list of loaded modules stored in sys. modules map (main 

module is under key _ main_ ). 

import module |.: alias] 

from module import name [as alias] ),....] 

from module import * 

reload (module) > module is reloaded (but existing references stili refer 
old module content) 

new. module (namel ,doc]) -> new module object. 

Import can use package path (ex:from encoding aliases 
import...). 

Direct import from a package use definitions from_ init_. py file. 

Very careful with import * as imported names override names 
already defined. 

To limit your modules names exported and visible by import *, 

define module global _all_ with list of exported names (or use 

global names xxx). 

See _import_ builtin function, and modules imp, ihooks. 

_import ( modulenamel, globalslJocalslJnamesIist]]]) 

Source encodings 

See PEP 263. Declare source files encoding in first or second line in 
a special comment. 

# coding- encodingjiame 

If this is not specified, Python use sys.getdefaultencodingO 
value (see modules sitecustomize.py and user.py). 

It is important to specify encoding of your modules as u”..." strings 
use it to correctly build Unicode literals. 

Special Attributes 

_name_ -> str: module name, ’_ main_ ' for command-line called 

script 
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_file_ -» string: pathname of compiled module loaded 

Main Execution / Script Parameters 

The 'main' module is the module called via command-line (or 
executed by Shell mith first script line #! /bin/env python). 
Command-line parameters are available in sys.argv (a python 

list). 

At end of module, we may have : 

if _name_=='_main_' : 

# main code 

# generally call a 'main* function: 
mainfunction(sys.argv[1:]) 

# or in lib modules, execute test/demo code... 

Execution exit after last main module instruction (in multithread, 
wait also for end of non-daemon threads), unless interactive mode 
is forced. 

Can force exit with calling sys . exit (code), which raise a 
SystemExit exception - see Current Process - Exiting (pl3). 

Operators 


Deal with arithmetic, boolean logic, bit level, indexing and slicing. 

Priority 


1 

(a,...) ra,...l 

6 

X+V 

*z y 

11 

x<v x<=v x>y x>=y x==y x!=y 

{a:b,...} '...' 

XOV X is V X is not V X in S 

X not in S 


2 

Sii1 sr /:/] 
s.attr f(...) 

7 

x«v 

x»v 

12 

not X 

3 

+x -x ~x 

8 

x&v 

13 

X and y 

4 

x**v 

9 

x A y 

14 

X or y 

5 x*y x/v x%y 

10 

x|y 

15 

lambda aras: expr 


Arithmetic Operators 

Can be defined for any data type. 


Arithmetic Overriding 

_add_ (self , other) -> value: called for self + other 

_sub_(self ,other) -> value: called for self - other 

mul_ (self , other) -> value: called for self * other 

_div_(self, other) -> value: called 1 for self / other 

_truediv_(self, other) -> value: called 2 for self / other 

_floordiv (self, other) -> value: called for self // other 

_mod_(self, other) -> value: called for self % other 

_divmod_ (self , other) -> value: called for divmod (self, other) 

_pow_ (self ,other) -> value: called for self ** other 

_nonzero_ (self) -> value: called for nonzero (self) 

_neg_ (self) -» value: called for -self 

_pos_ (self) -» value: called for +self 

_abs_ (self) -* value: called for abs (self) 

_i add_(self ,other) > called for self += other 

_isub_ (self ,other) > called for self -= other 

_imul_ (self ,other) > called for self *= other 

_idiv_ (self ,other) > called 1 for self /= other 

_i truediv (self , other) > called 2 for self /= other 

_if loordiv_ (self, other) ► called for self //= other 

_imod (self , other) > called for self %= other 

_ipow (self , other) *■ called for self **= other 

1 without / 2 with from_futur_import division 

Binary operators_xxx_have also_rxxx_forms, called when 

target object is on right side. 

Comparison Operators 
Operators can compare any data types. 

Compare values with < <= > >= == != <>. 

Test objects identity with is and is not (compare on id (obj )). 
Direct composition of comparators is allowed in expressions : 


x<y<=z>t. 

Builtin function cmp (ol,o2) -> -l (ol < o2), o (ol == o2), l (ol > o2) 
Comparison Overriding 

_lt_ (self, other) -> bool 1 : called for self < other 

_le_(self, other) -> bool 1 : called for self <= other 

_gt_ (self, other) -> bool 1 : called for self > other 

_ge_ (self, other) -* bool 1 : called for self >= other 

_eq_ (self, other) -> bool 1 : called for self == other 

_ne_ (self, other) -* bool 1 : called for self != other 

and for self <> other 

_cmp (self ,other)-> int: called for self compared to other, 

self<otber->value<0, self==otber->vaiue=0, self>other->value>0 

I 1 Any value usable as boolean value, or a Notimplemented value if 
| cannot compare with such other type. 

Operators as Functions 

Operators are also defined as functions in Standard operator 
module. 

Comparison 

lt (a,b) = _lt_ (a ,b) 

le(a,b) =_ le_ (a,b) 

eq (a,b) = _eq_ (a,b) 

Logica! / Boolean 

not _(0) — _not_ (0) 

truth (0) 
is _(a,b) 
is_not (a,b) 

Arithmetic 

abs (0) =_ abs_ (0) 

add (a, b) = _add_ (a, b) 

sub (a,b) = _sub_ (a,b) 

mul (a,b) = _mul_ (a,b) 

div(a,b) = _div_ (a,b) 

mod (a,b) = _mod_ (a,b) 

Bit Level 

lshift(a,b) =_ lshift_ (a,b) 

rshift(a,b) = _rshift_ (a,b) 

inv(O) =invert(0) - _inv_ (0) = _invert_ (0) 

Sequences 

concat (a,b) = _concat_ (a,b) 

contains (a ,b) = _contains_ (a,b) 

countOf (a,b) 
indexOf (a,b) 

repeat (a,b) = _repeat_ (a , b) 

setitem (a , b, C) = setitem (a,b,C) 

getitem(a,b) = getitem (a,b) 

delitem(a,b) - delitem (a,b) 

setslice (a , b, C, V) = setslice (a, b, C, V) 

getslice (a , b, C) =_ getslice_ (a , b, C) 

delslice (a,b,C) =_ delslice_ (a,b,C) 

Type Testing 

| These functions must be considered as not reliable. 

isMappingType (0) 
isNumberType (0) 
isSequenceType(o) 

Attribute and Item Lookup 
attrgetter (attr) -> fct: where fct(x)->x .attr 
itemgetter (item) -> fct: where fct(x)->x[/'tem] 

Booleans 

False : None, zero numbers, empty containers. False -> 0. 


ne(a,b) = _ne_ (d ,b) 

ge(a,b) — _ge_ ( d,b) 

gt (a,b) = _gt_ ( a,b) 

and _(a,b) = _and_ ( a ,b) 

or _(a,b) = _or_ (a,b) 

xor (a,b) = _ xor_ ( a,b ) 


truediv (a ,b) = _truediv_ (a ,b) 

f loordiv (a, b) = f loordiv ( a,b) 

neg(O) = neg (0) 

pos (0) = pos (0) 

pow {a,b) = _pow_ (d,b) 


True : if not false. True -> 1. 
bool ( expr) -> True | False 
Logical not : not expr 
Logical and : exprl and expr2 
Logical or : exprl or expr2 
Logical and and or use short path evaluation. 

Bool Cast Overriding 

nonzero (self) -* bool: test object itself 1 
Fif_ nonzero_undefined, look at_len_, else object is true. 

Numbers 

Builtin integer types : int (like C long), long (unlimited integer) 
int (expr[ , base=10]) -> int: cast of expr 
long (exprl r base=10}) -* long: cast of expr 

Builtin floating point types : float (like C double), complex (real and 
imaginary parts are float). 
float (expr) -» float; representation of expr 
complex (x[,yj) -> complex; number: x+yj 
[x+]yj -> complex; number, ex: 3+4j -8.2j 
c. real -> float; real part of complex number 
c . img -» float; imaginary part of complex number 
c. conjuga te () -» complex; conjugate of complex number (real,-img) 
Maximum int integer in sys.maxint. 

Automatic conversions between numeric types. 

Automatic conversions from intto long when resuit overflow max 
int. 

Direct conversions from/to strings from/to int, long... via types 
constructors. 

Type Decimal defined in Standard module decimal. 

Base fixed type compact storage arrays in Standard module array. 

Operators 

-x +x x+y x-y x*y x/y 1 x//y 1 x%y 2 x**y 2 

1 With from _ future _ import division, / is true division 

(l/2-*o . 5), and // is floor division (1//2—»o). Else for integers / is 
stili floor division. 

2 % is remainder operator, ** is power elevation operator (same as 
pow). 

Functions 

Some functions in builtins. 
abs (x) -> absolute value ofx 
divmod (x,y) -> (x/y,x%y) 

oct (integer) -> str: octal representation of integer number 
hex (integer) -> str: hexadecimal representation of integer number 
Representation formating functions in strings Formating (p6) and 
Localization (p7). 

Math Functions 

Standard floating point functions/data in Standard math module, 
acos (x) -* float: radians angle forx cosinus value : [-1...1] ->[0...n] 
asin (x) -* float: radians angle forx sinus value : [-1...1] — >[-n/2...+n/2] 
atan (x) -> float: radians angle for x tangent value : [-<»... t»] ->]-n/2... 

+ti/2 [ 

atan2 (x,y) -> float: randians angle for x/y tangent value 

ceil (x) -> float: smallest integral value >= x 

cos (x) -> float: cosinus value for radians angle x 

cosh (x) -> float: hyperbolic cosinus value for radians angle x 

exp(x) -> float: exponential of x = e" 

fabs (x) -> float: absolute value of x 

floor (x) -» float: largest integral value <= x 

fmod (x,y) -» float: modulo = remainder of x/y 

frexp(x) -> (float.int): (m,y) m mantissa ofx, y exponent ofx — where 
x=m*2 y 

ldepx (x,/) -> float: x multlplied by 2 raised to i power: x * 2' 
log(x) -* float: neperian logarithm ofx 
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logio (x) -* float: decimal logarithm ofx 

modf (x) -> (f loat{2}): (f,i) f signed fractional part of x, i signed integer 
part ofx 

pow(x,y) -> float: x raised to y power ( x y ) 
sin (x) -» float: sinus value for radians angle x 
sinh(x) -> float: hyperbolic sinus value for radians angle x 
sqrt (x) -> float: square root of x (Vx) 
tan (x) -> float: tangent value for radians angle x 
tanh(x) -* float: hyperbolic tangent value for radians angle x 
pi -> float: value of n (pi=3 . 1415926535897931) 
e -> float: value of neperian logarithms base 
(e=2. 7182818284590451) 

| Module cmath provides similar functions for complex numbers. 

Random Numbers 

Randomization functions in Standard random module. Module 
functions use an hidden, shared state, Random type generator 
(uniform distribution). 

Functions also available as methods of Random objects. 
seed ([x]) >■ initialize random number generator 
random() -* float: random value in [0.0, 1.0[ 
randint (a,b) -» int: random value in [a, b ] 
uniform (a, b)-» float: random value in [a, b[ 
getrandbits (k) -> long: with k random bits 

randrange (!start,]stop[ ,step]) -> int: random value in range (start, 
stop, step) 

choice ( seq) -> value: random item from seq sequence 
shuffle (x[ ,rndfct]) > items ofx randomly reordered using rndfct () 
sample (population ,k) -> list: k random items from polulation 
Alternate random distributions : betavariat e (alpha,beta), 
expovariate ( lambd) , gammavariate (alpha,beta), 
gauss (mu ,sigma), lognormvariat e (mu, sigma), 
normalvariate (mu ,sigma), vonmisesvariate (mu , kappa), 
paretovariate (alpha ), weibullvariate (alpha , beta). 

Alternate random generator wichmannHill class. 

Direct generator manipulation : getstate(), setstat s (state), 
jumpahead(n). 

In module os, see : 

os. urandom (n) -> str: n random bytes suitable for cryptographic use 
Other Math Modules 

Advanced matrix, algorithms and number crunching in third party 
modules like numpy (evolution of numarray / Numeric), gmpy 
(multiprecision arithmetic), Declnt, scipy, pyarray, ... 

See sites SciPy, BiQ Python, .PyS.cien.ce,... 

Numbers Casts Overriding 

_int_ (self) ->int: called for int (self ) 

_long_ (self) ->long: called for long (self ) 

_float_ (self) -rfloat: called for float (self ) 

_complex_ (self) -> complex: called for complex (self ) 

_oct (self) -* str: called for oct (self ) 

_hex (self) -* str: called for hex (self ) 

_coerce_ (self ,other) -> value: called for coerce (self ,other) 

Bit Level Operations 

Work with int and long data. 

Operators 
~x -»inverted bits ofx 
x A y -> bitwise exclusive or on x and y 
xsy -> bitwise and on x and y 
x|y -» bitwise or on x and y 
x«n -> x shifted left by n bits (zeroes inserted) 
x»n -> x shifted right by n bits (zeroes inserted) 

Binary structures manipulations in Standard module struet. 


Advanced binary structures mapping and manipulation in third 
party modules : ctypes, xstruct, pyconstruct, ... 

Bit Level Overriding 

_and_ (self ,other) -> value: for self & other 

_or_ (self, other) -> value: for self | other 

_xor_ (self ,other) -> value: for self * other 

_lshift (self ,other) -> value: for self « other 

_rshift (self , other) -> value: for self » other 

_invert_ (self) -* value: for -self 

_iand_ (self , other) > called for self s= other 

_ior_ (self ,other) > called for self | = other 

_ixor_ (self , other) > called for self A = other 

_ilshift (self,other) > called for self «= other 

_irshift (self ,other) > called for self »= other 

Strings 


Simple quoted 'Helio' or double-quoted "Helio". 

Use triple [simple|double] quotes for multi-lines strings : 

"""Helio, 

how are you ?""" 

Strings are immutable (once created a string cannot be modified in 
place). 

Strings can contain binary data, including null chars (chars of code 

0 ). 

Strings are sequences, see Indexing (p8) for chars indexation 
(slicing) and other operations. 
chr (code) -> str: string of one char 
ord (char) -* int: code 

str (expr) -> str: readable textual representation of expr - if available 
' expr' -» str: readable textual representation of expr - if available 
repr (expr) -> str: evaluable textual representation of expr - if available 


Escape sequences 

\a - bell 

\b - backspace 

\e - escape 

\f - form feed 

\n - new line 

\r - carriage return 

\t - horizontal tab 


\v - vertical tab 
\ ' - single quote 
\" - double quote 
\\ - backslash 

\ooo - char by octal ooo value 

\xhh - char by hexadecimal hh value 

\<newline> - continue string on next line. 


And for Unicode strings : 

\uxxxx - Unicode char by 16 bits hexadecimal xxxx value. 
\uxxxxxxxx - Unicode char by 32 bits hexadecimal xxxxxxxx value. 
\N{name) - Unicode char by name in the Unicode database. 

I Keep \ escape chars by prefixing string literals with a r (or r) - for 
| 'raw' strings (note : cannot terminate a raw string with a \). 

Unicode strings 

Quoted as for str, but with a u (oru) prefix before the string : 

u"Voigi" 

U"""Une bonne journee 
en perspective .""" 

| Can mix strings prefixs r (or r) and u (or o). 

You must define your source file encoding so that Python knows 
how to convert your source literal strings into internal Unicode 
strings. 

unichr (code) -> Unicode: string of one char 
ord (Unicode char) -> int: Unicode code 
Unicode (object[ r encoding[ ,errors]]) -> Unicode: Unicode 
sys .maxunicode -> int: maximum Unicode code=fct(compile time 
option) 

Unicode Chars Informations 


Module unicodedata contains informations about Unicode chars 
properties, names. 

lookup (name) -> Unicode: Unicode char from its name 

name (unichr[, default]) -> str: Unicode name - may raise ValueError 
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decimal (unichr[,default]) -> int: decimal value - may raise ValueError 
digit (unichr[,default]) -» int: digit value - may raise ValueError 
numeric (unichrl,default]) -> float: numeric value - may raise 

ValueError 

category (unichr) -> str: general Unicode category of char 
bidirectional (unichr) -a str: bidir category of char, may be empty 
string 

combining (unichr) -> str/0: canonical combining class of char as integer 
east_asian_width (unichr) -> str: east asian width 
mirrored (unichr) -> int: mirrored property in bidi text, 1 if mirrored else 
0 

decomposition (unichr) -> str: decomposition mapping, may be empty 
str 

normaliz e(form , unistr) -* str: normal form of string - form in 'nfc', 

1 NFKC ' , ' NFD ' , ' NFKD ' 

unidata_version -* str: version of Unicode database used 

Methods and Functions 

From builtins (see also oct and hex functions for integers to 
strings) : 

len (s) -> int: number of chars in the string 

Most string methods are also available as functions in the Standard 
string module. 

s. capitalize () -> string with first char capitalized 1 
s .center (width[ ,fillchar]) -> string centered 
s. count (sub[,start[,end]]) -> int: count sub occurences 
s. decode ([encoding] ,errors]]) -> Unicode: text decoded - see encodings 
(pl3) 

s. encode ([encoding] ,errors]]) -> str: text encoded - see encodings 
(pl3) 

s. endswith (suffixi, start[,end]]) ->bool: test text ending 
s.expandtabs ([ tabsize ]) -> string with tabs replaced by spaces 
s.find(sub[,start[,end]]) -> int/-l: offset of sub 

s. index (sub[,start[,encf]]) -> int: offset of sub - may raise ValueError 
s. isalnum () -»bool: non empty string with all alphanumeric chars 1 
s. isalpha () -> bool: non empty string with all alphabetic chars 1 
s. isdigit () -> bool: non empty string with all digit chars 1 
s. islower () -> bool: non empty string with all lower chars 1 

s.isspace () -> bool: non empty string with all space chars 1 

s. istitle () -> bool: non empty string with titlecase words 1 

s. isupper () -> bool: non empty string with all upper chars 1 

s.join(seg) -> string: seq[0]+s+seq[l]+s+...+seq[n-l[ 
s.ljust(w/cfth[ ,fillchar]) -> text string left aligned 2 
s. lower () -> text string lowered 1 

s. lstrip ([chars]) -> string text with leading chars 2 removed 
s.replac e (old,new[ ,count]) -> string with count firsts old replaced by 
new 

s.rfind(sub[,start[,end]]) -> int/-l: last offset of sub 
s.rindex(sub[,start[end]])-> int: last offset of sub - may raise 

ValueError 

s. r just (width \ ,fillchar]) -* string text right aligned 2 
s.rsplit([sep[,maxsp//t]])-> [string]: rightmost words delim. by sep 2 
s. rstrip ([cbars]) -> string with trailing chars 2 removed 
s.split ([sep[,maxsplit]]) -> [string]: words delimited by sep 2 
s. splitlines ([keepends]) -> [string]: list of text lines 
s.startswith(suffix[,start[,endj]) -* bool: test text begining 
s. strip( [chars]) -> string text with leading+trailing chars 2 removed 
s. swapcase () -> string with case switched 1 
s. title () -> string with words capitalized 1 
s. translate (table[ ,deletechars]) -> string: cleaned, converted 3 
s. upper () -» string uppered 1 

s. zfill (witdh) -> string: string prefixed with zeroes to mateh width 

1 Locale dependant for 8 bits strings. 

2 Default chars/separator/fillchar is space. 

3 For str table must be a string of 256 chars - see 

string. maketrans (). For Unicode no deletechars, and table must 
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| be a map of Unicode ordinals to Unicode ordinals. 

Formating 

Use % operator between format string and arguments : stringiargs 
Formating string contains %[ (name) ][flag][width][.precision]code 
If not use % (name)... -» args = single value or tuple of values. 

If use % (name)... -> args = mapping with name as keys. 

I For mapping, args can be an object with _getitem_ method - see 

| Overriding Mapping Operations (p8). 

Format char codes 
d signed int. decimal : -324 
° unsigned octal : 774 
x unsigned hexa : f3a 
e float. point exp. : -3 . 256e-12 
f float. point dec. : -0.0000032 
g like e or f 

c character (1 char str or code) 
r object format like repr (object) 

Templates 

With string. Template objects. Use common $ syntax : $$ >■ single 
$ ; $name or ${name) ► value for name. 
tmpl = string. Template (template_string) 
tmpi. substitute (mappingl ,**kwargs]) -> string: template filled 
tmpl. safe_substitute (mappingl, **kwargs]) -> string: template filled 
tmpl. template -> string 

I Can subclass Template to build your own templating (see doc, 

| sources). 

See also modules formatter. 

Wrapping 

Module textwrap has a Textwrapper class and tool functions. 
tw = textwrap . Textwrapper ([...]) -> new text wrapper using named 
params as corresponding attributes values 
tw.width -> int: max length of wrapped lines (default 70) 
tw. expand_tabs -> bool: replace tabs by text . expandtabs () (default 
True) 

tw . replace_whitespace -» bool: replace each whitespace by space 

(default True) 

tw. initial_indent -> string: prepend to first wrapped line (default ' ') 

tw. subsequent_indent -> string: prepend to other wrapped lines 

(default ' ' ) 

tw. fix_sentence_endings -* bool: try to separate sentences by two 

spaces (default False) 

tw. break_long_words -* bool: break words longer than width (default 

True) 

tw. initial_indent -> string: prepend to first wrapped line (default ' ') 
tw.wrap (text) -> [string]: list of text lines, each with max width length - 
no final newline 

tw.fill (text) -> string: whole text, lines wrapped using newlines 
Two convenient functions use temporary Textwrapper, built using 
named parameters corresponding to attributes. 
wrap (texti r width=lO[, ...]]) [string] 
fili (texti ,width= 70[ ,...]]) -> string 

dedent (text) -* string: remove uniform whitespaces at beginning of text 
lines 

Constants 

Standard module string provide several constants (do not modify, 
they are used in string manipulation functions) and some str 
functions are not available as methods. 
ascii_letters -» str: lowercase and uppercase chars 
ascii_lowercase -> str: lowercase a-z chars 
ascii_uppercase -* str: uppercase A-Z chars 
digits -> str: 0-9 decimal digit chars 
hexdigits -> str: 0-9a-fA-F hexadecimal digit chars 
letters -> str: lowercase and uppercase chars 1 
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lowercase -> str: lowercase a-z chars 1 
octdigits -> str: 0-7 octal digit chars 

punctuation -> str: ascii chars considered as punctuation in C locale 

printable -> str: printable chars 

uppercase -> str: uppercase A-Z chars 1 

whitespace -> str: whitespace chars (spe, tab, cr, If, ff, vt) 

capwords (s) -> str: split -» capitalize -»join 

maketrans (from ,to) -> translation table usable in str.translate - from and 
to must have same length 
| 1 Definition is locale dependant. 

Regular Expressions 

Standard module re has a powerfull regexp engine. See regexp 
FIOWTO at http://www.amk.ca/Dvthon/howto/reaex/ . 

Use raw string r"..." notation. 

I See also external projects pyparsing, PLY (Python Lex-Yacc), tpg 
| (Toy Parser Generator)... 

Expressions 

Metacharacters :. A $* + ?{}[]\ (), may use \ 

escape. 

. >■ mateh any character except a newline (including newline with dotall 
option) 

>• mateh start of string (and start of lines with multiline option) 

$ > mateh end of string (and end of lines with multiline option) 

expr* > mateh 0 or more repetitions of expr (as much as possible) 

expr+ > mateh 1 or more repetitions of expr (as much as possible) 

expr ? > mateh 0 or 1 expr 

expr*? >■ mateh like expr * but as few as possible 

expr+ ? > mateh like expr+ but as few as possible 

expr?? >■ mateh like expr? but as few as possible 

expr(m ) ► mateh m repetitions of expr 

exprdm], [n]} > mateh from m to n repetitions of expr, missing m default 
to 0 and missing n default to infinite 
exprdm], [n]} ? >■ mateh like expr{[m], [n]} but as few as possible 
[set] > mateh one char in the set defined by : 

“-iat begining, invert set definition 

x-y -> chars from x to y 

\x -> see Escape sequences for strings (p5) 

\- , \] -» chars - and ] (- and ] at the beginning mateh - and ] 
chars) 

x -> char x (including other re metacharacters) 
exprA | exprB > mateh exprA or exprB, short path evaluation 
(expr) *■ mateh expr and build a numbered group 

(?[i][L][m][s][u][x]) > (at least one ot iLmsux char) group mateh empty 
string, modify options flags for entire expression - see i L M s u x 
options 

(? : expr) *■ mateh expr but dont build a group 

(?p <name>expr) > mateh expr and build a group numbered and named 
( name must be valid Python identifier) 

(?p =name) > mateh text matehed by earlier group named name 
(?ttext) *■ no mateh, text is just a comment 
( ?=expr) > mateh if mateh expr but don't consume input 
( ? i expr) > mateh if doesn't mateh expr but don't consume input 
(?<=expr) >• mateh if current position is immediatly preceded by a mateh 
for fixed length pattern expr 

( ?< ! expr) > mateh if current position is immediatly not preceded by a 
mateh for fixed length pattern expr 
(? (num/name) yesexprl i noexpr ]) ► try to mateh yesexpr if group 
numlname exists, else try to mateh noexpr 
Escape Sequences 

\n \nn ► mateh 3 group number n ( nn ) where first n*0 
\ooo \0 o > mateh 3 char with octal value ooo (Oo) 

\A >■ mateh only at the start of the string 

\b >■ match3 empty string at beginning or end of a word 1+2 

\B >■ mateh empty string not at beginning or end of a word 1+2 
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i signed int. decimal : -324 
u unsigned decimal 6953 
x unsigned hexa : F3A 
e float. point exp. : -3.256E-12 
F float. point dec. : -0.0000032 
G like E or F 
%%%-»% 

s object format like str (object) 


\d ► mateh char class decimal digit [0-9] 

\D > mateh char class non-digit [ ^0—9 ] 

\s > mateh char class whitespace [ \t\n\r\f\v] 

\s ► mateh char class non-whitespace [ A \t\n\r\f\v] 

\w > mateh char class alphanumeric [a-zA-zO-9_] 

\w ► mateh char class non-alphanumeric [ A a-zA-zO-9_] 

\z ► mateh end of string 

\a \b \f \n \r \t \v \x \\ > same as string escapes 
\c > for other c chars, mateh char c 

1 Depends on UNICODE flag. 

2 Depends on LOCALE flag. 

3 When out of char class definition ( [...] ) 

Flag Options 

ignorecase (i) : case insensitive expression - not locale dependant. 
locale (l) : make \w \w \b \B locale dependant. 
multiline (m) : ~ and $ mateh begining/end of string and lines. Else 
and $ mateh only beginning and end of string. 
dotall (s) : make . mateh any char including newline. Else newline 
excluded. 

Unicode (u) : make \w \w \b \B Unicode dependant. 
verbose (x) : ignore whitespaces and make # starting comments 
(except when space and # are escaped or in char class). 

Matching and Searching 

Can use re functions, orcompile expressions into sre Pattern 
objects and use their methods. 

See Flag Options supra for flags parameters. 
search (pattern,stringi, flags])-> MatchObject/None: scan throught 
string to find substrings matching pattern 

mateh (pattern,stringi, flags]) -> MatchObject/None: try to mateh string 
with pattern 

split (pattern, stringi, maxsplit=0]) -> [string ]: split string by occurences 
of pattern - if maxsplit specified, remainder is put in last item of list 
findall (pattern,stringi, flags]) -> [string]/[ (string) ]: find non- 
overlapping substrings matching pattern - eventually empty matehs - 
return list of tuples if pattern has groups 

findi ter (pattern, stringi, flags])-* iterator over [Matchobject] - same 
as findall but with an iterator 

sub (pattern ,repl ,stringl ,count=0])-* string: replace substrings matching 
pattern by repi - repi as string can contain back references 1 to identified 
substring - repi as fct(MatchObject) return replacement string - pattern 
may be RE_Pattern object 

subn (pattern,repi,stringi ,count=0])-> (string,int): same as sub, 2 nd 
item is count of substitutions 

escape (string) -> string: non-alphanumeries backslashed 

If you need to reuse a pattern, compile it one time for ali. 
pat = re. compile (patternl, flags I) -> RE Pattern object 
pat . mateh (stringi ,posl,endpos]]) -* same as mateh function 2 
pat. search (stringi ,posl,endpos]]) -> same as search function 2 
pat. split (stringi, maxspl/t=0])-> same as split function 2 
pat. findall (stringi,posl ,endpos]]) -> same as findall function 2 
pat. findi ter (stringi ,posl ,endpos] ]) -> same as findi ter function 2 
pat. sub(rep/ , stringi, count=0])-> same as sub function 
pat. subn (pattern,repi,stringi ,count=0])-* same as subn function 
pat. flags -* int: flags used at compile time 
pat . pattern -> string: pattern used at compile time 
pat . groupindex -> dict: mapping of group names to group numbers 
Several functions/methods return Matchobject objects. 
m.expand (template) -> string: do backslash substitution on template (like 
sub method) using mateh object groups values 
m. group (Igroupl ,..,]]) -> string/ (string): subgroups of the mateh from 
numbers or names 

m. groups (ldefault=None]) -* (string): ali subgroups of the mateh - 
default give access to subgroups not in the mateh 
m.groupdict([defau/t=Wone])-> dict: name->subgroup: all named 
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subgroups of the match - default give access to subgroups not in the 
match 

m. start (lgroup=0]) -* int: index of start of substring matched by group, 
-l if group exists but not in match 

m.end([group=0])-> int: index of end of substring matched by group, -l if 
group exists but not in match 

m. span ([group=0]) -> (int{2}): values of start and end methods for the 
group 

m.pos -> int: pos value of search/match method 
m. endpos -> int: endpos value of search/match method 
m.lastindex -» int/None: index of last matched capturing group 
m.lastgroup -> string/None: name of last matched capturng group 
m. re -» RE Pattern: pattern used to produce match object 
m. string -> string: string used in match/search to produce match object 
1 Back references extended to \g <groupnum> and \g<groupname>. 

1 Using part of string between pos and endpos. 

Group number 0 correspond to entire matching. 

Localization 

Standard module locale provide posix locale Service (internationa- 
lization). 

setlocale (categoryl , locale]) -> current/new settings: if locale specified 
(as string or as tuple(language code, encoding)) then modify locale 
settings for category and return new one - if locale not specified or None, 
return current locale - not thread safe 
localeconv () -> dict: database of local conventions 
nl_langinfo ( option)-* string: locale-specific informations - not available 
on ali Systems - options may vary on Systems - see options p7 
getdefaultlocale ([envvars]) -»(language code, encoding): try to 
determine default locale settings 

getlocale ([category]) -> current lc_* setting for category - category 
default to lc_ctype - for language code and ancoding it may be None 
getpreferredencoding (! do_setlocale]) -> str: user preffered encoding 
for text data - set do_setlocale to False to avoid possible call to 
setlocale () 

normalize ( localename) -> normalized locale code for localename - usable 
with setlocale// - return localename if normalization fails 
resetlocale ([category]) *■ reset locale for category to default setting - 
category default to lc_all 

strcoll (sl,s2) -> int: compare two strings - follow lc_collate setting 
- return 0 if sl==s2, <0 if sl<s2, >0 if sl>s2 

strxfrm (string) -> string:transform string for locale-aware comparison 
format (format,val[,grouping]) string:convert val float using format (% 
operator conventions) - follow lc_numeric settings (decimal point, + 
grouping if it is true) 

str (float) -> string: convert float - follow lc_numeric settings (decimal 
point) 

atof ( string) -> float: convert string to float - follow lc_numeric settings 
atoi ( string) -» int: convert string to integer - follow lc_numeric settings 
char_max -> symbolic constant used by localeconv () 

Categories 

lc_ctype -» character type - case change behaviour 
lc_collate -> strings sorting - strcoll () and strxfrm( ) functions 
LC_TIME -» time formating - time, strftime () 

lc_monetary -» monetary values formating - options from localeconv () 
lc_messages -» messages display - os.strerror () - not for Python 
messages 

lc_numeric -> numbers formatting - formato , atoi () , atof () and 
str () of this module (dont modify normal Python number formating) 
lc_all -> ali locales - used to change/retrieve the locale for ali categories 


nljanginfo options 


key 

nl langinfoO value usage 

CODESET 

name of character encoding 

D_T_FMT 

usable as format for strf time () for time and 
date 


key 

nl langinfoO value usage 

D_FMT 

usable as format for strftime() for date 

T_FMT 

usable as format for strf time () for time 

T_FMT_AMPM 

usable as format for strftime () for time in 
am/pm format 

DAY_1...DAY_7 

name of the n th day of the week - first day is 
sunday 

ABDAY_1.. . 

ABDAY 7 

abbreviated name of the n th day of the week - 
first day is sunday 

MON l... MON l2 

name of the n th month 

ABMON_l.. . 

ABMON 12 

abbreviated name of the n th month 

RADIXCHAR 

radix character (decimal dot/comma/...) 

THOUSEP 

separator character for thousands 

YESEXPR 

regular expression (of C library!) usable for yes 
reply 

NOEXPR 

regular expression (of C library!) usable for no 
reply 

CRNCYSTR 

currency Symbol, preceded by - if should appear 
before the value, by + if should appear after the 
value, by . if should replace radix character 

ERA 

era - generally not defined - same as e format in 
strftime ( ) 

ERA_YEAR 

year in era 

E RA_D_T_FMT 

usable as format for strftime () for date and 
time with era 

ERA_D_FMT 

usable as format for strftime () for date with 
era 

ALT_DIGITS 

up to 100 values representing 0 to 99 


localeconv keys 


key 

meaning 

currency Symbol 

Local currency Symbol for monetary values. 

decimal point 

Decimal point character for numbers. 

f rac_digits 

Number of fractional digits used in local 
formatting of monetary values. 

grouping 

[Int] : relative positions of 'thousands_sep' 
in numbers. char max at the end stop 
grouping. 0 at the end repeat last group. 

int curr Symbol 

International currency Symbol of monetary 
values. 

int_frac_digits 

Number of fractional digits used in 
International formatting of monetary 
values. 

mon decimal point 

Decimal point used for monetary values. 

mon grouping 

Equivalent to 'grouping 1 , used for monetary 
values. 

mon thousands sep 

Group separator used for monetary values. 

n_cs precedes 

True if currency Symbol preceed negative 
monetary values, false if it follow. 

n sep by space 

True if there is a space between currency 
Symbol and negative monetary value. 

n sign posn 

Position of negative sign for monetary 
values 1 . 

negative sign 

Symbol used to annotate a negative 
monetary value. 

p_cs_precedes 

True if currency Symbol preceed positive 
monetary values, false if it follow. 

p sep by space 

True if there is a space between currency 
Symbol and positive monetary value. 

p_sign posn 

Position of positive sign for monetary 
values 1 . 

positive sign 

Symbol used to annotate a positive 
monetary value. 

thousands_sep 

Character used between groups of digits in 


key 

meaning 


numbers. 


1 Possible values : 0=currency and value surrounded by 
parentheses, l=sign should precede value and currency Symbol, 
2=sign should follow value and currency Symbol, 3=sign should 
immediately precede value, 4=sign should immediately follow 
value, LC_MAX=nothing specified in this locale. 

Multilingual Support 

Standard module gettext for internationalization (I18N) and 
localization (L10N) Services - based on GNU gettext API + higher 
interface. See docs for explanations about tools usage. 

Base API 

bindtextdomain (domainl ,/ocaledir]) -> str: bounded directory - bind 
domain to localedir directory if specified (used when searching for .mo 
files) 

bind_textdomain_codeset (domainl ,codeset]) -> codeset binding: bind 
domain to codeset if specified - change xxgettext() returned strings 
encoding 

textdomain ([domain]) -* global domain: set global domain if specified 
and not None 

gettext ( message) -> string: localized translation of message - based on 
current global domain, language, and locale directory - usually aliased as _ 
in local namespace 

lgettext (message) -> string: like gettext (), using preferred encoding 
dgettext (domain , message) -* string: like gettext (), looking in 
specified domain. 

idgettext (domain,message)-» string: like dgettext (), using preferred 
encoding 

ngettext (singular,plural,n) -> string: like gettext (), but consider plural 
forms (see Python and GNU gettext docs) 

lngettext (singular,plural,n)-> string: like ngettexto, using preferred 
encoding 

dngettext (domain.singular,plural,n) -> string: like ngettexto , looking 
in specified domain. 

ldngettext (domain,singular r plural,n)-> string: like dngettexto , 
using preferred encoding 

Generally _ is bound to gettext. gettext, and translatable strings 
are written in sources using _( ' thestring' ). See docs for usage 
examples. 

Class based API 

The recommended way. Module gettext defines a class 
Transi at ions, dealing with .mo translation files and supporting 

str/unicode strings. 

find (domain[ ,localedir[ ,languages[ ,ail]]])-> str/None: .mofile name 
for translations (search in localedir/language/LC_MESSAGES/domain.mo) 
translation (domainl, localedirl ,languages[, class_[, fallbackl, codeset] 
]]]]) -«Translations: object from class class_ (default to 
GNUTranslations, constructor take file object as parameter) - if true 
fallback allow to return a NullTranslations if no .mo file is found, 
default to false (raise iOError) - codeset change charset used to encode 
translated strings 

install (ctoma/n[,/oca/ed/r[ ,un/coc(e[,codeset]]]) > install _ function in 

Python's builtin namespace, to use _ ( ' thestring' ) 

Null Translations 

The NullTranslations is a base class for ali Translations. 

t. _init_ ([fp]) > initialize translations: fp is a file object - call 

_parse (fp) if it is not None 

t._parse (fp) > nothing: subclasses override to read data from the file 
t . add_fallback (fallback) > add fallback used if cannot found 
translation for a message 

Define methods gettext, lgettext, ngettext, lngettext as in the 
base API. And define speciale methods ugettext and ungettext 
returning Unicode strings (other forms return encoded str strings). 
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Return translated message, forwarding to fallback if it is defined. 
Overriden in subclasses, 
t. info () -* return protected _info attribute 
t.charset () -> return protected _charset attribute 
t. output_charset () -> return protected _output_charset attribute 
(defining encoding used to return translated messages) 
t. set_output_charset (charset) > set _output_charset attribute 

t. install ([Unicode]) >- bind_in builtin namespace to 

self .gettexto or self. ugettext () upon Unicode (default to false) 

GNU Translations 

The GNUTranslations class (subclass of NullTranslations) is 

based on GNU gettext and .mo files. 

Messages ids and texts are coerced to Unicode. 

Protected _info attribute contains message translations. 

Translation for empty string return meta-data (see doc). 

Define methods gettext, lgettext, ugettext, ngettext, 
lngettext, ungettext as in NullTranslations interface - Same 
rules for return values (str/unicode). Message translations are 
searched in catalog, then in fallback if defined, and if no translation 
is found, message itself is returned (for n... methods, return 
singular forms if n=l else plural forms). 

CoNTAINERS 

Basic containers kind : 

-sequences (ordered collections) : list, tuple,str, any iterable,... 
-mappings (unordered key/value) : dict... 

-sets (unordered collections) : set, frozenset... 

Operations on Containers 

For strings, items are chars. For mappings, items are keys. 

item in Container -> bool: test item £ Container 1 

item not in Container -> bool: test item £ Container 1 

for var in Container: ... > iterate var over items of Container 

len (Container) -> int: count number of items in Container 2 

max (Container) -> value: biggest item in Container 

min (Container) -> value: smallest item in Container 

sum(container) -> value: sum of items (items must be number-compatible) 

I 1 For strings test if expr is a substring of sequence. 

| 2 Container must provide direct length method - no generator. 
Copying Containers 

Default containers constructors build nem Container with references 
to existing objects (shallow copy). To duplicate content too, use 
Standard module copy. See Copying Objects (p3). 

Overriding Containers Operations 

_len_ (self) -> int: called for len (self) 

_contains_ (self , item) -* bool: called for item [not] in self 

pYou can override iterable protocol on containers too. 

Sequences 

Sequences are ordered collections : str, Unicode, list, tuple, 
buffer, xrange, array . array... any user class defining sequences 
interface, or any iterable data. 

Lists & Tuples 

Builtin types list and tuple store sequences of any objects. 

Lists are mutable, tuples are immutable. 

Declare a list : [ilenV ,...]] 

Declare a tuple : (item] ,...]) 

Notes: [] ► empty list; () ► empty tuple ; (item,) > one item 
tuple. 

list (object) -> list: new list (cast from object / duplicate existing) 
tuple (object) -> tuple: new tuple (cast from object / duplicate existing) 
range ([start, ]stop[, step])-* [int]: list, arithmetic progression of 
integers 

xrange 1 ([start, ]stop[ ,step]) -> xrange: object generating arithmetic 
progression of integers 


Unless using a sequence as a mapping key, or ensuring it is 
immutable data, prefer list to tuple. 

1 Use in place of range to avoid building huge lists just for indexing. 

Operations on Sequences 

See Operations on Containers (p8) too. 
seql + seq2 -> concatenation of seql and seq2 
sequence * n -> concatenation of sequence duplicated n times 
n * sequence -> concatenation of sequence duplicated n times 
reversed ( sequence) -> iterator throught sequence in reverse order 
sorted (sequence[ ,cmp[,key[, reverse]]]) -* list: new list, sorted items 
from iterable - see list. sorted () 

filter 1 (fct,sequence) -> list: new list where fct(item) is True. Use None 
fct for a boolean test on items 

map 1 (fct,sequence -» list: new list where i th item is fct( i th items of 
sequence(s)) 

reduce (fct,sequence[ ,initializer])-> value: fct applied cumulatively to 
sequence items, f(f(...f(f(f(initializer,a),b),c,...) 

zip 1 (sequence,,,,) -> list: list of tuples, i th tuple contains i th items of each 
sequences 

I 1 See Iteration Tools (p9) as replacement (avoid creating a new 
I list). 

Indexing 

Use index [/] and slice [ i:j[:step ] syntax. Indexs zero-based. 
Negative indexs indexing from end. Default step is 1, can use 
negative steps. 

Sub-sequences indexs between items. 


1 = [ei,e 2 ,e 3 , 

e n _ 2 , e n _i. 

e n ] 

1 [0]—t e! 

1[0:n] 

->[e 1 ,e 2 ,e 3 ,...,e n _ 2 , 

1[1]-* e 2 

![:]—*■ 

[ei, e 2 , e 3/ —/ e n - 2 1 e n - 

1 [-2] —> e 

1 [i:]- 

[6i+i, ei+ 2 , Gi+ 3 ,e 

1[-1]— e» 

1 [:i]- 

->[ei,e 2 ,...,ei- 2 ,ei-i. 



items indexs 


-n 

-n + l 

-n+2 


-2 

-i 

0 

1 

2 


n-2 

n-l 

ei 

e 2 

e 3 

...item... 

e n -i 

e n 


0 

i 

2 

3 


n-2 

n-l 

n 

-n 

-n+l 

-n+2 

-n+3 


-2 

-1 



slicing indexs 


Slice objects 

Defines index range objects, usable in [] notation. 

slice ([start, ]stop[ ,step]) -> slice object 

siice. indices (len) -> (int{3}>: (start,stop,stride) 

Ordered sets of data indexed from 0. Members start, stop, step. 

Extended Slicing 

Multiple slices notation - corresponding to a selection in a multi- 
dimension data - can be written using notation like 
[ a , x:y:z , : , : , : , m:n ] . 

Ellipsis notation can be used to fili multiple missing slices, like 
[ a , x:y:z , ... , m:n ]. See docs. 

| Three dot notation ... is replaced internally by Ellipsis object. 

Operations on mutable sequences 
Mutable sequences (ex. list) can be modified in place. 

Can use mutable sequence indexing in left part of assignment to 
modify its items : seq[index]=expr ; seq(start:stop]=expr ; 
seq [start: stop: step ] =expr 
seq .append (item) > add item at end of sequence 
seq .extend (otherseq) *■ concatenate otherseq at end of sequence 
seq. count (expr) -> int: number of expr items in sequence 
seq. index (expr[,start[,stop]])-* int: first index of expr item 


seq .insert (index,item) > item inserted at index 
seq. remove (expr) *■ remove first expr item from sequence 
seq.pop ([index]) -»item: remove and return item at index (default -1) 
seq. reverse () > items reversed in place 

seq . sort ([cmp][ , key][ , reverse]) >- items sorted in place - cmp : 
custom comparison fct(a.b), retval <0 or = 0 or >0 - key : name of items 
attribute to compare - reverse : bool 
dei seq [index] > remove item from sequence 
dei seq [start:stop[ :step]] > remove items from sequence 
Overriding Sequences Operations 

_getitem (self , index 2 ) -> value: item at index, called for 

self [index] 

_setitem_ 1 (self ,index 2 , value) *■ set item at index to value, called 

for self [index] =value 

_de litem_ 1 (self ,index 2 ) > remove item at index, called for 

dei self [/ndex] 

1 Only for mutable sequences. 

2 Parameter index can be a slice [start,stop,step] - replace old 

_getslice_,_setslice_,_delslice_. 

Can also override arithmetic operations _add (concatenation ) 

and mul_ (repetition ), Container operations and object 

operations. 

Mappings (dictionaries) 

Builtin type dict. Store key:value pairs. 

Declare a dictionary : ( key: value [,,..]) {} 

dict()-> dict: empty dictionary (like {}) 

dict (**kwargs)-> dict: from named parameters and their values 

dict (iterable) -* dict: from (key,value) by iterable 

dict (otherdict) -> dict: duplicated fro another one (first level) 

Operations on Mappings 

See Operations on Containers (p8) too, considering operations on 
keys. 

d[key] -> value for key 1 
d[key]=value *■ set d[key] to value 
dei d[key] *■ removes d[key] from d 1 

d. fromkeys (iterablel, va/ue=None]) -> dict: with keys from iterable and 
ali same value 

d. ciear () > removes ali items from d 
d . copy () -> dict: hallow copy of d 

d.has_key (k) -> bool: test key presence - same as k in d 
d. items () -> list: copy of d's list of (key, item) pairs 
d.keys () -* list: copy of d's list of keys 
d. update (otherd) > copy otherd pairs into d 
d.update (iterable) > copy (key,value) pairs into d 
d. update (**kwargs) > copy name=value pairs into d 
d. values ()-> list: copy of d's list of values 
d.get(key,defva/)-> value: d[key] if key£d, else defval 
d. setdefault (key[ ,defval=None]) -> value: if key$d set d[key] =defval, 
return d[key] 

d.iteritems ()-> iterator over (key, value) pairs 
d. iterkeys () -> iterator over keys 
d. itervalues () -* iterator over values 

d. pop (key [, de fi/a/]) -* value: dei key and returnsthe corresponding 
value. If key is not found, defval is returned if given, otherwise KeyError 
is raised 

d.popitem () -> removes and returns an arbitrary (key, value) pairfrom d 
1 If key doesn't exist, raise KeyError exception. 

Overriding Mapping Operations 

_getitem (self ,key) -> value for key, called for self [key] 

_setitem_ (self , key, value) > set value for key, called for 

self [key] =va/ue 

_de litem (self , key, value) > remove value for key, called for 
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dei self [key] 

| Can also override Container operations and object operations. 

Other Mappings 

For on-disk mappings, see Standard module shelve, and database 
modules . 

For ordered mappings see third party modules OrderedDict. 

Sets 

Unordered collections of unique items. Frozen sets are immutable 
once created. 

set ([iterable]) -> set: using values from iterable 
frozenset ([iterable]) -> frozenset: using values from iterable 

Operations on Sets 

See Operations on Containers (p8) too. 

s. issubset ( others) -> bool: test s c others 

s. issuperset ( others) -> bool: test others c s 

s. add (item) > add item to set 

s. remove (item) > remove item from set 1 

s. ciear () ► emoves all items from (notforzen) set 

S . intersection (others) -> set: S n others 

s i others -* * set: s n others 

s . union (others) -> set: s u others 

s | others -> set: s u others 

s. dif ference (others) -> set: [x / xGs and x$others] 
s - others -> set: [x / xGs and xfcothers] 

S . symmetric_diff erence (others) -> set: [x / xGs xor xGothers] 
s A others -» set: [x / xGs xor xGothers] 
s. copy () -* set: shallow copy of s 
s.update (iterable) > adds all values from iterable to s 

I 1 Raise KeyError if object not in set. 

| Results set have same type as s object (set/frozenset). 

Other Containers Structures, Algorithms 

Generally containers follow Python idioms, you can use : len (cont), 
cont[i], for item in cont:... 

Array 

Standard module array provides efficient array of basic types. It 
uses compact storage for elements of same type. 


Type Codes 


n 

tc 

C type 

py type 

n 

tc 

C 

py type 

i 

'b' 

signed char 

int 

i 

'B' 

unsigned char 

int 

i 

' c ' 

char 

str 

2 

' u ' 

Unicode char 

Unicode 

2 

'h' 

signed short 

int 

2 

'H' 

unsigned short 

int 

2 

' i' 

signed int 

int 

2 

' I ' 

unsigned int 

long 

4 

'1' 

signed long 

int 

4 

’ L ' 

unsigned long 

long 

4 

' f' 

float 

float 

8 

'd' 

double 

float 


n=size in bytes, tc=char typecode to use 


Functions 

array (tc,[iterable]) -> array: with typecode tc, initialized from iterable 

a . typecode -sstr: typecode of a data 

a . itemsize -> int: bytes size of a data 

a . append (expr) > append item expr to end of a 

a. extend (array) > append items from another array 

a . count (expr) -> int: number of expr items 

a. index (expr) -> int: first index of expr item 

a. insert (index, expr) > expr item inserted at index 

a . remove (expr) > remove first expr item 

a.pop ([/ndex]) -a value: return and remove item at index (default -1) 
a. reverse () >• items in array are reversed 

a.buffer_info() -> (int{2}>: current storage infos (address.items 
count) 

a .byteswap () > swap bytes of array items 


a. fromfile (f,n) *■ append n items read from real binary file f 1 
a. tofile (f) *■ write all items to real binary file f 
a. fromlist (list) > extend array from values in list 
a.tolistf) -> list: items in a list 

a. fromstring (s) > extend array from values in binary buffer s (string) 
a. tostring () -> str: items in binary representation 
a. fromunicode (s) *■ extend 'u' array from data in Unicode stirng 
a. tounicode () -* Unicode: convert ‘u 1 array to Unicode string 

1 if less items than needed, get available ones then raise 
EOFError . 

Old methods read and write replaced by fromfile and tofile. 

Queue 

Standard module collections provides queues management. 
deque ([iterable]) -» deque: initialized from iterable 
q. append (x) >■ add x to right side of deque 
q. appendlef t (x) >■ add x to left side of deque 
g. ciear () >• remove all elements from deque 
q .extend (iterable) *■ extend right side of deque with iterable items 
q. extendlef t (iterable) *■ extend left side of the deque with iterable 
items 

q . pop () -> item: pop and return item from dequeue right side 
q.popleft() -> item: pop and return item from dequeue left side 
q. rotate (n) > rotate deque from n steps, to right if n>0, to left if n<0 
Can also use Standard operations on sequences : len(g) , 
reversed (q) , copy. copy (q), copy. deepcopy (q), item in q, q [ -1 ], 
and serialization via pickling protocol. 

Priority Queues 

Standard module heapq. Structure a list as a priority queue. 
heapify (x) > transform list x into heap 
heappush (heap,item) > push item onto heap 
heappop (heap) -> item: pop and return smallest item from the heap 
heapreplace (heap, newitem) -> item: pop and return smallest item from 
the heap, push newitem 

nlargest (n, iterable)-> list: n largestfrom iterable 
nsmallest (n,iterable) ->list: n smallest items from iterable 

Sorted List 

Standard module bisect maintains lists sorted (via basic bisection 
algo). 

bisect_left (list,item[,lo[,hi]])-> int: index to insert item at leftmost 
sorted position 1 

bisect_right (list ,item[ ,lo[,hi]])~* int: index to insert item at 
rightmost sorted position 1 
bisect (...) > alias for bisect_right (...) 

insort_left (list,item[ ,lo[ ,hi]]) > insert item at leftmost sorted 
position 1 

insort_right (list,item[,lo[,hi]]) > insert item at rightmost sorted 
position 1 

insort (...) >- alias for insort_right (...) 

| 1 With list previously sorted. 

Iteration Too Is 

Standard module itertools provides some practical iterators. 
chain (iterable! iterator over items of several iterables 

count ([start])-* iterator over integers from start (default 0) 
cycle (iterable) ->iterator cycling over iterable items 
dropwhile (predicatefct, iterable) -> iterator over items of iterable where 
predicatefct] item) is false 

groupby (iterable] ,keyfct]) -> iterator over (key value,group 1 of items 
where keyfct(item)=key value), default keyfct is identity 
ifilter (predicate, iterable) -> iterator over items of iterable where 
predicatefct] item) is true - None predicate filter items being true 
if ilterf alse (predicate, iterable) -> iterator over items of iterable where 
predicatefct] item) is false - None predicate filter items being false 
imap (function,iterabjel ,. : .J) -»iterator over ftrnct/on(items at same index 
from iterables 2 ), None function return tuples items 


islic s(iterable , [start, ]stop[ ,stepj) -> iterator over items at slice 3 indexs 
from iterable, None stop goes up to end 

izip (iterable'. ,.... )--> iterator over tuple(items at same index from 
iterables) 

repeat (objecti, count])-> iterator returning object over and over again, up 
to count times (default to infinite) 

starmap (function,iterable) -> iterator over function(*tuple item from 
iterable) 

takewhile (predicatefct, iterable) -> iterator over items of iterable where 
predicatefct(item) is true 

tee (iterable[ ,n]) -> n independent iterators from same iterable 4 , default 
n=2 

1 Group of items is internally used - must save it as list if needed 
after current iteration. 

2 Stop at end of shorter iterable. 

3 Slice parameters cannot be negative. 

4 Don't use iterable out of tee created iterators. 

Date & Time 

Module time 

Standard module time defines common functions and data. 

Date & Time Data 

• float_time = float containing seconds from 'epoch' (january 1 
1970 on Unix - see gmtime (0) ), with sub-second precision in 
decimal part. 

• tuplejtime = tuple containing 9 int (see table). 

• struct tlme = tuple/object with int attributes (see table). 


# 

attribute 

value 

# 

attribute 

value 

0 

tm year 

int 

5 

tm sec 

0...61 

1 

tm mon 

1...12 

6 

tm wday 

0...6 (monday=0) 

2 

tm mday 

1...31 

7 

tm yday 

0...366 

3 

tm hour 

0...23 

8 

tm isdst 

0 (no) 

1 (yes) 

-i (unknown) 

4 

tm min 

0...59 




• float_delay = float containing seconds, with sub-second 
precision. 

DST is local time, UTC is universal (GMT) time. 
accept2dyear -> [rw] bool: accept two-digit year values (default true), 
modifiable via environment var PYTHONY2K 

altzone -> Int: offset (pos/neg) in seconds of DST relatively to UTC, in 
seconds, use only if daylight is true 
daylight -> int: *0 if a DST timezone is defined 
timezone -> int: offset (pos/neg) in seconds of local (non DST) timezone 
tzname -> (str{2}) : names of local timezone (non-DST, DST) 

Functions 

asctime ([t= 2 ])-> str: build local time string from t (tuple_time or 
struct_time) 

clock () -> float: processor time in seconds, for accurate relative time 
measurement 

ctime ([secs= 2 ]) -> str: build local time string from float_time second 
gmtime ([secs= 2 ]) -* struct time: convert float_time to UTC struct_time 
local time([secs= 2 ])-> struct time: convert float time to DST 
struct_time 

mktime (t)-» float time: convert DST t (tuple_time or struct_time) to 
float_time - may raise OverflowError or ValueError 
sleep (secs) *■ execution suspended during secs (float delay) times, 
maybe less (signal catching), may be more (process/threads scheduling) 
strftime (formati ,t= 2 ]) -> str: build time string from t (tuple time or 
struct_time) using format string (table infra) - may raise ValueError 
strptime (stringi, format]) -» struct time: parse string using time 
format 1 - may raise ValueError 
time () -> float_time: current UTC time 

tzset () > resets time conversion rules accordingly to environnment 
variable TZ - unix only, see docs 
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1 Default format "%a %b %d %H:%M:%S %Y". Missing values 
default to (1900, 1, 1, 0, 0, 0, 0, 1, -1) 

2 Param secs default to current time, param t default to local 
current time. 


Time format strings 


%a 

Abbreviated weekday name 1 . 

%A 

Full weekday name 1 . 

%b 

Abbreviated month name 1 . 

%B 

Full month name 1 . 

%c 

Appropriate date and time 
representation 1 . 

%d 

Month day [01,31]. 

%H 

Hour [00,23]. 

%I 

Hour [01,12]. 

%j 

Year day [001,366]. 

%m 

Month [01,12]. 

%M 

Minute [00,59]. 

%p 

AM or PM 1 . 

%S 

Second [00,61]. 

%U 

Year week [00,53] (Sunday 
based). 

%w 

Week day [0,6] (0=Sunday). 

%W 

Year week [00,53] (Monday 
based). 

%x 

Appropriate date 
representation 1 . 

%X 

Appropriate time representation 1 . 

%y 

Year [00,99]. 

%Y 

Year (with century). 

%z 

Time zone name (no characters 
if no time zone exists). 

%% 

Literal % char. 


1 Locale language representation. 


Module datetime 

Standard module datetime has tools for date/time arithmetics, data 
extraction and manipulation. 

Defines class : timedelta, time, date, datetime, [tzinfo]. 

Module timeit 

Standard module timeit has functions to measure Processing time 
of code. It can be used in Scripts (see docs), or directly in command 
line : 

python -mtimeit j n N] [-r N] [-s S] [-t] [-c] [-h] [statement [...]] 

-n N / ~number=N execute statement N times 
-r N / ~repeat=/V repeat timer N times (default 3) 

-s S / ~setup=S executed S once initially (default pass) 

-t /-time use time . time () (default except Windows) 

-c /-clock use time. clock() (default on Windows) 

-v / -verbose print raw timing results - may repeat option 
-h / -help print help and exit 

Other Modules 

Standard module calendar has functions to build calendars. 

See also third party module mxDateTime. 

Files 

Normal file operations use Python file objects (or file-like objects 
with same interface). Some functions directly manipulate files path 
names (strings). Functions mapping low level OS handlers (mainly 
those in Standard os module) use numeric file descriptors (fd also 
known as fileno). 

Raw data use str type (can contain any data byte values, including 

0 ). 

File Objects 

Standard file type is builtin file. It defines the Python file protocol. 
Create a file : file (filenamel ,mode= ' r' [,bufsize]]) -> file object 
Mode flags (combinable) : 'r' read, 'w' write new, 'a' write 
append, ’ + ’ update, 'b' binary 1 , 'U' universal newline 2 . 

Buffer size : o unbuffered, l line buffered, >1 around that size. 
OpenQ is an alias for file() 

1 Default text mode tries to interpret newline sequences in the file. 

2 Automatically choose newline sequence in CR or LF or CR+LF 
adapted from file/to platform. 

Methods and Functions 
f. close () > file flushed and no longer usable 
f. fileno () -> int: low level file descriptor (fd) 
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f. flush() >■ buffers written to file on disk 
f. isatty () -> bool: indicator file is a terminal 
f. read ([s/ze]) -> str: block of data read from file 
f. readline () -> str: next line read from file, end of line removed 
f. readlines () -> [string]: list of ali lines read from file, end of lines 
removed 

f. seek (offset[ r whence= 0]) > modify current position in file - whence: 0 
from start, l from current, 2 from end 
f. teli () -> Int: current position in file 
f. write ( string ) >• data written to file 

f. writelines ( listofstrings ) >• data written to file (no end of line added) 
for line in f :... > iterate line over lines of f 

Old method xreadlines replaced by iteration on file object. 

For optimized direct access to random lines in text files, see 
module linecache 

Attributes 

f. closed -> bool: indicator file has been closed 
f. encoding -> str/None: file content encoding 
f. name -> str: name of the file 

f. newlines -> str/tuple of str/None: encountered newlines chars 
f. sof tspaoe -» bool: indicator to use soft space with print in file 

Low-level Files 

Base low-level functions are in Standard module os. 

| Careful of clash with builtins with os.open name. 

open (path ,flags[ ,mode=077 7])-> int (fd): open file path - see flags infra 
- mode masked out with umask 

fdopen (fd[ ,mode[, bufsize]]) -> file: build a file connected to fd - 
mode and bufsize as for builtin open () + mode must start with r or w or a 
dup (fd) -* int (fd): duplicate file descriptor fd 

dup2 (fd,fd2) -> int (fd): duplicate file descriptor fd into fd2, previously 
closing fd2 if necessary 
close (fd) > close file descriptor 

read (fd,n)-> str: read as mostn bytes from fd file- return empty string if 
end of file reached 

write (fd,str) -> int: write str to fd file - return number of bytes actually 
written 

lseek (fd,pos,how) > setfile descriptor position - how. o from start, l 
from current, 2 from end 

fdatasync (fd) > flush file data to disk - don't force update metadata 
(Unix) 

f sync (fd) > force low level OS buffers to be written 
f truncate (fd ,iength) > truncate file descriptor to at most length (Unix) 

Open Flags 

Constants defined in os module, use bit-wise OR (x | y | z) to mix 
them. 

o_rdonly -> read only 

o_wronly -> write only 

o_rdwr -> read/write 

o_append -> append each write to end 

o_creat -> create new file (remove existing) 

o_excl -» with o_creat, fail if file exist (Unix) 

o_trunc -> reset existing file to zero size 

o_dsync -> xxxxxx (Unix) 

o_rsync -> xxxxxx (Unix) 

o_sync -> return from 10 when data are physically written (Unix) 

o_ndelay -> return immediatly (don't block caller during IO) (Unix) 

o_nonblock -> same as o_ndelay (Unix) 

o_noctty -> terminal device file can! become process tty (Unix) 

o_binary -> don't process end of lines (cf+lf from/to cr) (Windows) 

o_noinherit -> xxxxxx (Windows) 

o_short_lived -> xxxxxx (Windows) 

o_temporary -> xxxxxx (Windows) 


o_random -> xxxxxx (Windows) 
o_sequential -> xxxxxx (Windows) 
o_text -> xxxxxx (Windows) 

Pipes 

For Standard process redirection using pipes, see also Simple 
External Process Control (pl4). 

os. pipe () -> ( (int{2}) {2}): create pair (fdmaster.fdslav) offd 
(read,write) for a pipe 

os .mkfifo (path[ ,mode=0666]) > create named pipe path - mode 
masked out with umask - don't open it (Unix) 

Use os functions on file descriptors. 

In-memory Files 

Memory Buffer Files 

Use Standard modules stringio and cStringlO to build file-like 
objects storing data in memory. 
f = StringlO . Stringio () 

Build a file-like in memory. 
f. write (string) > data written to file 
f. ...other file writing methods... 
f. getvalue () -» str: current data written to file 
f. close () >■ file no longer usable, free buffer 
cStringlO is a compiled (more efficient) version of StringlO for 
writing. Optional argument allows to build memory files to read 
from too. 

f = cStringlO . StringlO ([string]) 

f. read(ls/zej) -> str: block of data read from 'file' (string) 
f. ...other file reading methods... 

Memory Mapped Files (OS level) 

Standard module mmap manage memory-mapped files, usable as 
file-like objects and as mutable string-like objects. 

To build a memory map : 

mm = mmap. mmap (fileno,length] ,tagname[,access]]) [Windows] 

mm = mmap. mmap (fileno ,length[, flags] ,prot[,access]]]) [unixj 
Use an os file descriptor (from os .open () or from file-objecfs 
fileno ()) for a file opened for update. 

Length specify amount of bytes to map. On Windows, file may be 
extended to that length if it is shorter, it can! be empty, and 0 
correspond to maximum length for the file. 

Access (keyword param) : access_read (readonly), 
access_write (write-through, default on Windows), or 
access_copy (copy-on-write). 

On Windows, tagname allow to identify different mappings against 
same file (default to None). 

On Unix, flags : map_private (copy-on-write private to process) 
or map_shared (default). And prot (memory protection mask) : 
PROT_READ or PROT_WRITE, default is PROT_READ I PROT_WRITE. If 
use prot+flags params, don't use access param, 
mm. close () > mmap file no longer usable 
mm. find (stringi ,start= 0 ]) -» int: offset / -l 
mm. flush ([offset,size]) > write changes to disk 
mm .move (dest,src,count) > copy data in file 
mm. read ([s/ze] )-> str: block of data read from mmap file 1 
mm. read_byte () -> str: next one byte from mmap file 1 
mm. readline () -> str: next line read from file, end of line is not 
removed 1 

mm.resize ( newsize) > writable mmap file resizer 
mm. seek (offset[ ,whence=o]) > modify current position in mmapfile- 
whence: 0 from start, l from current, 2 from end 
mm. size () -> int: length of the real os file 
mm. teli () -> int: current position in mmap file 
mm .write (string) > data written to mmapfile 1 

mm. write_byte (byte) > str of one char (byte) data written to mmap 
file 1 

1 File-like methods use and move file seek position. 
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Files Informations 

Functions to set/get files informations are in os and in os .path 
module, some in shutil module. Constants flags are defined in 
Standard stat module. 

I Some functions accessing process environment data (ex. current 
| working directory) are documented in Process section. 

os. accsss (path, mode)-> bool: test for path access with mode using real 
uid/gid - mode in f_ok, r_ok, w_ok, x_ok 
os. f_ok -» access mode to test path existence 
os ,r_ok -» access mode to test path readable 
os ,w_ok -» access mode to test path writable 
os ,x_ok -» access mode to test path executable 

os. chmod (path,mode) > change mode of path - mode use stat.s_* 
constants 

os.chown (path, uid, gid) > change path owner and group (Unix) 
os.lchown (path, uid, gid) *■ change path owner and group - don't 
follow symlinks(Unix) 

os. f stat (fd) -» int: status for file descriptor 

os. f statvfs (fd) -> statvfs resuit: informations about file system 
containing file descriptor (Unix) 

os. stat (path) -> stat structure object: file system informations (Unix) 
os.lstat (path)-> stat structure object: file system informations (Unix) - 
dont follow symlinks 

os. stat_float_times ([newvaiue]) -> bool: test/set stat function time 
stamps data type - avoid setting new value 

os. statvfs (path) -> statvf s result: informations about file system 
containing path (Unix) 

os. utime (path, times) > set access and modification times of file path - 
times=(atime,mtime) (numbers) - times=None use current time 
os. fpathconf ( fd,name) -> str / int: system configuration information 
about file referenced by file descriptor - see platform documentation and 
pathconf_names variable - name str or int (Unix) 
os.pathconf (path, name)-> str / int: system configuration information 
about file referenced by file descriptor - see platform documentation and 
pathconf_names variable - name str or int (Unix) 

os. pathconf_namss -> dict: name -> index - names accepted by 

pathconf and fpathconf -> corresponding index on host (Unix) 
os .path.exists (path) -> bool: test existing path - no broken symlinks 
os .path.lexists (path) -> bool: test existing path - allow broken 
symlinks 

os .path.getatime (path) -»float_time: last access time of path 
os .path.getmtime (path) -»float_time: last modification time of path 
os .path.getctime (path) -< float_time: creation time (Windows) or last 
modification time (unix) of path 

os.path. getsize (path) -» int: bytes size of path file 
os .path.isabs (path) -> bool: test absolute 
os .path. isfile (path) -> bool: test regular file (follow symlinks) 
os .path. isdir (path) -> bool: test existing directory (follow symlinks) 
os .path.islink (path) -> bool: test symlink 
os .path. ismount (path) -> bool: test mount point 
os .path. samefile (pathl ,path2)-> bool: test refer to same real file 
(unix.macos) 

os .path. sameopenfile (fl ,f2)-> bool: test opened files referto same 
real file (unix.macos) 

os. path. samestat (stati ,stat2)-> bool: test stat tuples refer to same 


file (unix.macos) 

shutil. copymode (srcpath,dstpath) > copy normal file permission bits 
shutil. copystat (srcpath,dstpath) > copy normal file permission bits 
and last access and modification times 


Stat Structures 

stat_result is returned by stat and lstat functions, usable as a 
tuple and as object with attributes : 


# 

attribute 

usage 

0 

st mode 

protection bits 

1 

st ino 

inode number 


# 

attribute 

usage 

2 

st dev 

device 

3 

st nlink 

number of hard links 

4 

st uid 

user ID of owner 

5 

st gid 

group ID of owner 

6 

st size 

size of file, in bytes 

7 

st atime 

time of most recent access 

8 

st mtime 

time of most recent content modification 

9 

st ctime 

time of most recent metadata change on Unix, time of 
creation on Windows 


st blocks 

number of blocks allocated for file (Unix) 


st blksize 

filesystem blocksize (Unix) 


st rdev 

type of device if an inode device (Unix) 


st rsize 

size of resource fork, in bytes(MacOS) 


st creator 

file creator code (MacOS) 


st_type 

file type code (MacOS) 


statvfs_result is returned by fstatvfsand statvfs functions, 
usable as a tuple (use statvfs variable indexs) and as an object 
with attributes : 


# 

attribute 

index var 

usage 

0 

f bsize 

F BSIZE 

preferred file system block size 

1 

f frsize 

F FRSIZE 

fundamental file system block size 

2 

f blocks 

F BLOCKS 

total number of blocks in the filesystem 

3 

f bfree 

F BFREE 

total number of free blocks 

4 

f bavail 

F BAVAIL 

free blocks available to non-super user 

5 

f files 

F FILES 

total number offile nodes 

6 

f ffree 

F FFREE 

total number of free file nodes 

7 

f favail 

F FAVAIL 

free nodes available to non-super user 

8 

f flag 

F FLAG 

flags - see host statvfsQ man page 

9 

f namemax 

F NAMEMAX 

maximum file name length 


Stat Constants 


Defined in Standard stat module. 

S_ISUID -» XXXXX 
S_ISGID -> XXXXX 
S_ENFMT -» XXXXX 
S_I SVTX -» XXXXX 
s_iread -> 00400 user can read 
s_iwrite -» 00200 user can write 
s_iexec -> 00100 user can execute 
s_irwxu -> 00700 user can read+write+execute 
s_irusr -> 00400 user can read 
s_iwusr -> 00200 user can write 
s_ixusr -* 00100 user can execute 
s_irwxg -> 00070 group can read+write+execute 
s_irgrp -* 00040 group can read 
s_iwgrp -* 00020 group can write 
s_ixgrp -> 00010 group can execute 
s_irwxo -> 00007 everybody can read+write+execute 
s_iroth -> 00004 everybody can read 
s_iwoth -> 00002 everybody can write 
s_ixoth -> 00001 everybody can execute 
Terminat Operations 

os. openpty () -* (int{2}>: open pseudo-terminal 1 pair 
(fdmaster,fdslave)=(pty,tty) (Unix) 

os. ttyname (fd) -> str: terminal device associated to fd (Unix) 
os. isatty (fd) -> bool: test file descriptor is a tty-like (Unix) 
os. tcsetpgrp (fd,pg) >• set process group id associted with terminal fd 
(Unix) 

os. tcgetpgrp (fd) -> Int: process group associated with terminal fd 
(Unix) 

See also Standard modules tty and pty. For user-interface control 
on text terminal , see Standard package curses and its sub- 


modules. 

Temporary Files 

Use Standard tempfile module. It defines several functions to make 
life easier and more secure. 

TemporaryFile([mode='w+h , [ , bufsize=-l [ ,suffix[ ,prefix[ ,d/r]]]]]) 

-* file/file-like: temp file - removed on close - not necessary visible in file- 
system - dir and prefix as for mkstemp 
NamedTemporaryFile([mode= , W+b '[ , bufsize=- 
1[,suffixi,prefixl,dir]]]]]) 

-* file/file-like: like TemporaryFile - file visible in file-system 
mkstemp (i suffixi ,prefix[ ,dir[, text]]]]) -* (Int,str): (fd.path) of new 
temporaty file - no race condition - only creator can read/write - no 
executable bit - not automatically deleted - binary mode unless text 
specified 

mkdtemp (lsuffixi ,prefixl,dir]]]) -> str: path of new temporary directory 
created - no race condition - only creator can read/write/search - not 
automatically deleted 

gettempdir () -> str: default directory for temporary files 
gettempprefix () -* str: default filename prefix for temporary files 

Other functions in tempfile and os modules are kept for code 
compatibility, but are considered not enough secured. Also 
tempdir and template data in tempfile which should not be 
used directly. 

Path Manipulations 

Path manipulation functions are in Standard os.path module. 
supports_unicode_f ilenames -> bool: Unicode usable for file names 
abspath (path) -> str: normalized absolutized pathname 
basename (path)-> str: file name part of path 

commonprefix (pathlist) -> str: longest common path prefix (char-by- 
char) 

dirname (path) -> str: directory name of pathname 
join (path.,...]) > str: concatenate path components 
normcase (path) -* str: normalize path case for platform (see doc) 
normpath (path) -* str: normalize path (// /./ /../), on Windows /-> \ 
realpath (path)-> str: canonical path (remove symlinks) (unix) 
split (path)-> (str{2}): split into (head, last pathname component) 
splitdrive (path) -> (str{2}): split into (drive, tail) 
splitext (path)-> (str{2}): split into (root, ext) 

Host Specific Path Data 

sys . getf ilesystemencoding () -> str: name of encoding used by 
system forfilenames 

Following data are in os and in os.path. 

curdir -> str: string used to refer to current directory 

pardir -> str: string used to refer to parent directory 

sep -> str: char used to separate pathname components 

altsep -> str: alternative char used to separate pathname components 

extsep -> str: char used to separate base filename from extension 

pathsep -> str: conventional char to separate different paths 

Directories 

os .listdir (path) -> [str]/[unicode]: list names in path directory - 
without . and . . - arbitrary order - path string type -> item strings type 
os .mkdir (pathl,mode=0777]) > create directory path - mode masked 
out with umask 

os .makedirs (pathl,mode=0777]) > create directory path, recursively - 
mode masked out with umask - dont handle Windows' UNC path 
os.rmdir (path) > remove directory path 
os . removedirs (path) ► remove directories, recursively 
os .walk (top[ ,topdown=True [ ,onerror=None]]) -> iterable: go throught 
dirs under top, for each dir yield tuple(dirpath, dirnames, filenames) - 
onerror= fct(os.error) - see docs 

os .path. walk (path, visit,arg) > call visit(arg, dirname,names) for dirs 
rooted at path - may modify names (files list) to influence walk, may prefer 
to use os. walk 
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Special Files 

os. link (src,dst) > create hard link named dst referencing src (Unix) 
os. symlink (src,dst) > create symbolic link named dst pointing to src 
(Unix) 

os. readlink ( path ) -> str: path pointed to by symbolic link 
os. mknod (path [, mode=0666,device]) ► create FS node (file, device 
special file, named pipe) - mode = permissions | nodetype - node type in 
s_ifreg, s_ifreg, s_ifchr, s_i fblk, and s_ififo defined in stat 
module 

os .major (device) -> int: raw device major number 
os .minor (device) -> int: raw device minor number 
os .maked ev (major, minor) > compose raw device from major and minor 
numbers 

Copying, Moving, Removing 

os. remove ( path) > remove file path (not directory) 
os. rename ( src,dst) > rename src to dst - on same filesystem- may 
remove existing dst file 

os. renames (old, new) ► rename otd to new, recursively - try to create 
intermediate directories 

os. unlink (path ) > remove file path (not directory) - same as remove 

Standard module shutil provides high level functions on files and 
directories. 

copyf ile (src, dst) > copy normal file content - overwrite destination 2 . 
copyfileobj (fsrc,fdst[, length=16kb]) > copy file-like object content by 
blocks of length size (<0=one chunk) 

copy (src, dst) > copy normal file content to file/directory 2 - in case of 
directory use same basename as src - overwrite destination - copy 
permission bits, 

copy2 (src, dst ) > same as copy + copy last access and modification 
times 2 . 

copytree (src ,dst[ ,symlinks= False]) >■ recursively copy directory tree - 
destination must be new - files copied via copy - if symlinks is False, copy 
symbolic links files content, else just make symbolic links. 1 
rmtree (path[, ignore_errors=Falsel , onerror=None]j) >■ recursively 
delete directory tree - onerror= fct(fctref, path, excinfo). 1 
move (src, dst) > recursively move file or directory tree - may rename or 
copy. 1 

I 1 May raise shutil.Error exception. 

| 2 Params src and dst are files path names. 

Encoded Files 

Standard module codecs have functions and objects to 
transparently process encoded files (used internally as Unicode 
files). 

codecs .open (filename, mode[ ,encoding[ ,errors[, buffering]]]) -> file-like 
EncodedFile object with transparent encoding/decoding 
codecs .EncodedFil e (file,input[ ,output[ ,errors ]]) -> file-like wrapper 
around file, decode from input encoding and encode to output encoding 
codecs .BOM -» str: alias for BOM_UTF16 
codecs . BOM_BE -* str: alias for BOM_UTF16_BE 
codecs . BOM_LE -> str: alias for BOM_UTF16_LE 
codecs . BOM_UTF8 -> str: ' \xef \xbb\xbf ' 

codecs ,BOM_UTFl6 -> str: alias for BOM_UTFl6_LE Or BOM_UTF16_BE 
codecs . BOM_UTFl6_BE -> str: ' \xfe\xf f 1 
codecs ,BOM_UTF16_LE -» str: ' \xff \xfe' 

codecs ,BOM_OTF32 -> str: alias for BOM_UTF32_LE Or BOM_UTF32_BE 
codecs. BOM_UTF32_BE -> str: ' \x00\x00\xfe\xff ' 
codecs . BOM_OTF32_LE -* str: ' \xff\xfe\x00\x00 ' 

I See Encoding - Decoding (pl3) for details about encoding and 
| errors. 

Serialization 

Standard modules pickle and cPickle (speed up to lOOOx) have 
support for data serialization of objects hierarchies. 

See Python documentation. 

| See also module marshal (read/write of Python data in platform 


I independant binary format - but can broke format between 
| releases). 

Persistence 

Standard module shelve use pickling protocol to store objects in 
DBM files (see pl7) and access them via a dictionnary-like 
interface with keys as str. 

open (filenamei ,flag[ ,protocoi( ,writeback[,binary]]]]) -> dictionary-like 
object - flag as anydbm.open (pl7), default to 'c' - protocol default to 0 
(ascii format) - writeback: cache accessed entries in memory and written 
them back at close time, default to False - binary is deprecated, use 
protocol. 


Configuration Files 

Standard module ConfigParser. It uses Standard .INI files to store 
configudation data : 

[section] Values can contain % (name) s references which 

name :value may be expanded using values in same section 

name=value or in defauits 

# and ; start comment lines. 

Module defines 3 configuration classes with different data access 
level : 

RawConfigParser 
ConfigParser 


SafeConfigParser 

rp— RawConf igParser ([defauits]) -> RawConf igParser 
cp=Conf igParser ([defau/ts]) -> ConfigParser 
sp=SafeConf igParser ([defau/ts]) -* SafeConf igParser 
In the three constructors, defauits is a dict of option:value for 
references expansion. 

max_interpolation_depth -> int: max recursive depth for get() when 
raw parameter is false 

defaultsect -> str: name of defaut section 


Raw Interface 

rp. defauits () -* dict: default values for references expansion 
rp. sections () -* [string]: list sections in config (without DEFAULT) 
rp. add_section ( section ) > add a new section - may raise 

DuplicateSectionError 

rp. has_section (section) -* bool: test if section exists - eant test for 
DEFAULT 

rp. options (section) -> [string]: list options in section 
rp. has_option (section,option) -> bool: test if section and option exists 
rp.iead(lfilename]/filename)-> [filename]: try to load configuration data 
from files (continue if fail) - return names of loaded files 
rp .readfp (fp[, filename]) > load configuration data from f ile/file-like 
rp .get (section , option) -> str: option value 
rp. getint (section,option) -> int: coerce option value to int 
rp .getfloat (section,option)-» float: coerce option value to float 
rp. getboolean (section,option)-> bool: coerce option value to bool - 
True is strings 1 yes true on - False is strings 0 no false of f - may 
raise ValueError 

rp. items (section)-» [ (name, value) ]: options in the section 
rp. set (section, option, value) >• set option to string value in section - may 
raise NoSectionError 

rp. write (fileobject) *■ write configuration data to file 
rp. remove_option (section,option)-» bool: return True if there was 
such option - may raise NoSectionError 

rp. remove_section (section)-» bool: return True if there was such 
section 

rp. optionxform (option) -> str: normalized internal form of option 
Normal Interface 

cp .get (section,optioni,raw[,vars]])-> string: value for option in section - 
% interpolation expanded unless raw is true - vars is a dict of additional 
defauits - reference expansion names are processed by optionxform () 
for matehing 

cp. items (sect/on[ ,raw[, vars]]) -> [ (name,value) ]: for given section - 


raw and vars as in get() 

Safe Interface 

sp. set (section.option,value) > set value string for section and option 
Exceptions 

(Exception) 

Error 

ParsingError 

NoSectionError 
DuplicateSectionError 
MissingSectionHeaderError 
NoOptionError 
InterpolationError 

InterpolationDepthError 
InterpolationMissingOptionError 
InterpolationSyntaxError 

For similar file format supporting nested subsections, see 
ConfigObj config parser. For Windows users, Standard module 

_winreg 

For text-file configs, can use XML tools, and see also third party 
YAML parsers like PyYaml 

Exceptions 

Standard exceptions defined in exceptions module, and available 
in current scope. 

AII exceptions must be subclasses of Exception root class. 

Use Standard exceptions if their meaning correspond to you errors. 
Subclass Standard exceptions when needed. 

Standard Exception Classes 

Exception 

stopiteration — iterator's next(), no more value. 

SystemExit — sys.exitQ called 
StandardError — built-in exceptions 
ArithmeticError — arithmetic errors. 

FloatingPointError 
OverflowError 
ZeroDivisionError 

AssertionError — assert condi,message] failed. 
AttributeError — attribute set/get failed. 

EnvironmentError — host System error - see arg tuple attribute 

IOError 

OSError 

windowsError — Windows error codes. 

EOFError — end-of-file with input () or raw_input(). 

ImportError 

Keyboardlnterrupt — user interrupt (Ctrl-C). 

LookupError 

indexError — non-existent sequence index. 

KeyError — non-existent mapping key. 

MemoryError 

NameError — non-existent name in current scope. 

UnboundLocalError — reference to an unassigned local 
variable. 

ReferenceError — try accessing weak-ref disposed object. 
RuntimeError — (prefer defining ad-hoc subclasses). 

NotlmplementedError 

SyntaxError 

IndentationError 

TabError 

SystemError — a bug... in Python. 

TypeError 

ValueError — good type, but bad value. 

UnicodeError 

Warning — warnings superclass (see Warnings infra) 

UserWarning 
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PendingDeprecationWarning 

DeprecationWarning 

SyntaxWarning 

RuntimeWarning 

Warnings 

Warnings must be subclasses of Warning root class. 

Standard warnings module control Processing of warning 
exceptions. 

warn (messagel,category] ,stacklevel]]) 

warn_explicit (message , category, filename, linenol , module[, registry ] 

]) 

showwarning ( message, category, filename, linenol , file]) 
forma twarning ( message, category, filename, lineno) 
filterwarnings (actioni, messagel ,category[ ,module[ , linenol,append] 

]]]]) 

resetwarnings () 
sys . warnoptions 

Exceptions Processing 

sys ,exc_info () -* (type, value, traceback) for current exception 1 
sys. exc_clear () ► current exception related informations cleared 
sys . excepthook -* (rw) fct(type, value, traceback) called for uncaught 
exceptions 

sys. _excepthook_ -* backup of original excepthook function 

sys . tracebacklimit -> int: (rw) maximum levels of traceback printed, 
<=0 for none 

| 1 Or (None,None,None) if no running exception. 

Standard module traceback has tools to process and format these 
informations. 

Encoding - Decoding 

Standard module codecs provide base support for encoding / 
decoding data. This is used for character encodings, but also for 
data compression (zip, bz2) ordata representation (uu, hex). 

See Unicode strings (p5), Source encodings (p3). 

See functions, classes and constants for files encoding in Encoded 
Files (pl2). 

Module encodings. aliases. 

Threads & Synchronization 

Python threads use native threads. A global mutex (the GIL) lock 
interpreter data during Python Virtual instructions execution (it is 
unlocked during l/O or long computation in native code). Check for 
thread switching and signal Processing is performed at regular 
interval. 

sys. getcheckinterval () -> int: current thread switching check 
interval 1 

sys. setcheckinterval ( interval) > set hread switching check interval 1 

| 1 Expressed in number of Python Virtual instructions. 

Threading Functions 

Use Standard high level module threading which provides several 
classes : Thread, local (for thread local storage), Event, Lock and 
RLock (mutex), Semaphore and BoudedSemaphore, Timer. 

Module threading also provides functions : 
activeCount () -> int: number of currently active threads 
currentThread () -» Thread: current running thread 
enumerate ()-> [Thread]: list of active threads 
settrace (fune) > install trace function called before threads run 
methods 

setprof ile (fune) >■ install profile function called before threads run 
methods 

Standard module thread supports low level thread management. 
Use modules dummy_thread and dummy_threading on platforms 
without multithreading. 


Threads 

Class threading. Thread is used to create new execution path in 
current process. It must be called with keyword arguments. Specify 
thread code with a callable target param or by overriding run 

method (remember calling inherited_ init_ in subclasses), give 

arguments in args and kwargs (tuple and dict), give a name to 
identify the thread - group currently not used (None). 
th = threading. Thread (group , target , name, args, kwargs) 
th. start () > start thread activity (in another thread) 
th. run () > thread code to execute - call target if not overriden 
th. join (Itimeout]) *■ wait for th termination or timeout elapsed 
(float delay, default to None for infinite) 
th. getName () -* str: thread associated name 

th. setName (name) > set thread associated name (initial name set by 
class) 

th. isAlive () -> bool: test thread alive (started and run() not terminated) 
th. isDaemon () -> bool: test thread have daemon flag 
th. setDaemon ( daemonie) *■ set thread daemon flag - must be called 
before start. Initial flag inherited from creating thread. Python process exit 
only after last non-daemon thread termination. 

| A thread can't be killed or paused externally by another thread. 

Thread Local Storage 

Class threading. local attributes values are thread local. 

Subclass it or use it as a namespace. 

tlsdata = threading.local() 
tlsdata.x - 1 

Delayed Start Thread 

Class threading. Timer is a subclass of Thread which effectively 
run after a specified interval from its start. 
t = threading. Timer ( interval, function,args= [] ,kwargs ={}) 
t. cancel () >■ timer will never run - must not be already running 
Create a timer that will run function with arguments args and 
keyword arguments kwargs, after interval seconds have passed. 

Mutual Exclusion 

Classes threading. Lock and threading. RLock provide mutual 
exclusion between threads. Lock doesn't allow a thread to re- 
acquire a lock it already owns, RLock does (reentrant-lock). 
lock = threading. Lock () 
lock = threading. RLock () 

lock. acquire ([blocking]) -> bool/None: acquire the lock. blocking 
unspecified : wait & return None : blocking true : wait & return True ; 
blocking false : don't wait (try) & return True/False 
lock. release () >■ unlock a previously acquired lock 

Must release a lock same times as it was acquired. 

Good practice to acquire/release locks in try/finally blocks. 

For portable inter-process mutex, see third party glock.py module. 

Events 

Class threading. Event is a synchronisation flag with thread 
blocking mechanism to wait for the flag. 

evt= threading. Evento > new event, with internal flag setto False 
evt. isSet () -* bool: value of event internal flag 
evt. set () > set event internal flag to true - unlock waiting threads 
evt. ciear () > set event internal flag to False 

evt. wait ([t/meout]) ► wait for event internal flag to be true - timeout is a 
float delay (default to None=infinite blocking) 

General purpose events scheduler 
Module sched provides such a tool, adaptable to your needs ('time' unit is 
yours). 

sc = sched. scheduler (timefunc,delayfunc) -* scheduler: timefunc 
return numbers mesuring time, delayfunc(n) wait n time (same unit as 
timefunc output) - typically sc = 
sched . scheduler (time . time , time. sleep) 


sc . enterabs (time,priority,action,args) -> evtid: schedule a new event, 
will call action (*args) at time 

sc .enter (delay,priority,action,args) -> evtid: schedule a new event, will 
call action (*args) after delay 

sc. cancel (evtid) > remove scheduled event - may raise RuntimeError 

sc. empty ()-> bool: test if scheduler events queue is empty 

sc . run () > run scheduled events at their scheduling time - see docs 

Semaphores 

Classes threading. Semaphore and threading. BoundedSemaphore 
provide simple semaphore for resources counting (without/with 
counter checking). 

sem = threading. Semaphore (lvalue=l]) > semaphore with initial 
counter 

sem = threading. BoundedSemaphore ([va/ue]) 

sem. acquire dblocking]) -> bool/None: acquire the semaphore (consume 
one resource). blocking unspecified : wait & return None : blocking true : 
wait & return True ; blocking false : don't wait (try) & return True/False 
sem . release () >■ release the semaphore (free one resource) 

Condition Variables 

Class threading. Condition allows threads to share state (data) 
protected via a Lock. Important : condition variables (lock) must 
be acquired when calling wait, notify or notifyAll. See Python 
docs. 

cond = threading. Condition ([/ocfc]) >• build new condition variable, 
use user providen lock (Lock or RLock) else build a new RLock 
cond. acquire (*args) -> value: acquire cond. var. lock, return 
lock.acquire() value 

cond. release () > release cond. var. lock 

cond. wait ([t/meout]) > wait until notified or timeout elapsed- timeout is 
a float_delay (default to None=infinite blocking). Release cond. var. lock 
and wait for a notification/timeout then re-acquire lock. 
cond . notify () > wake up one waiting thread (if any). 
cond. notifyAll () ► wake up ali waiting threads. 

Synchronized Queues 

Module Queue provides a class Queue to store data in a 
synchronized FIFO queue, and two exception classes Full and 
Empty. In blocking mode, full queue block producers and empty 
queue block consumers (in non-blocking mode they raise 
exceptions). Other organization can be built with subclassing (see 
source for internal methods). 

q = queue. Queue ( maxsize) > build new queue - infinite queue if 
maxsize<=0 

q. qsize () -» int: size of the queue - at call time 
q. empty () -» bool: test if queue size if 0 - at call time 
q. full () -> bool: test if queue size is maxsize - at call time 
g.put (iteml ,blockl , timeout]]) > put item in queue - block can be 
true/false, timeout can be None/float_delay. May raise Queue. Full 
exception. 

q.put_nowait (item) > same as put (item, False) 
q.get ([blockl,timeout]])-> item: removed from queue - block can be 
true/false, timeout can be None/float_delay - may raise Queue .Empty 
exception 

q.get_nowait() > same as get (False) 

Process 

Current Process 

Standard module os has tools to get Information about and 
manipulate current process and its environment. 

Exiting 

Normally Python process exit when there is no more non-daemon 
thread running. 

sys .exit (larg=0]) *■ exit via a SystemExit exception (may be catch) - 
arg is exit code 
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os._exit (n) >• exit without cleanup 

os .aborto >■ exit via a SIGABRT signal (signal may be handled) 
Following exit codes are defined in os (Unix) : 


EX OK 

no error 

EX USAGE 

command used incorrectly 

EX DATAERR 

incorrect input data 

EX NOINPUT 

unavailable/inaccessible input 

EX NOUSER 

unknown user 

EX NOHOST 

unknown host 

EX UNAVAILABLE 

required Service unavailable 

EX SOFTWARE 

internal error 

EX OSERR 

OS error 

EX OSFILE 

missing/inaccessible file 

EX CANTCREAT 

can't create output 

EX IOERR 

error during file l/O 

EX TEMPFAIL 

temporary failure 

EX_PROTOCOL 

illegal/invalid/not understood protocol 
exchange 

EX NOPERM 

not enough permissions (out of file perms) 

EX CONFIG 

configuration problem 

EX_NOTFOUND 

missing data 


You can install exit functions (for normal exit) with module atexit. 
register(ftjnc[,*args[,**kargs]j) ► register function to be called with args 
and kargs 

Registered functions are called in reverse order of registration. 
Bypassed when process is terminated by a signal, an internal error, 
or an os ._exit. 

Environment Variables 

environ -> dict: environment variables - modification call putenv if 
supported 

getenv (varname[ ,default=None])-> str: environment variable value 
puten v(varname , value) > set environment variable - affect later started 
subprocess - may cause memory leaks (see platform documentation) 

Some functions also in os.path : 

expanduser (path) -> str: path with initial or "~user" replaced 
expandvars ( string) -> str: string with $name or $ (nane) environment 
variable replaced 

Directory, Files, Terminat 

I See also Console & Interactive Input/Output (p2), and Files - 
| Terminal Operations (pll). 

chdir (path) > change current working directory to path 
fchdir (fd) > change current working directory to thus represented by file 
descriptor 

getcwd () -> str: current working directory 
getcwdu () -* Unicode: current working directory 
chroot (path) > change process file-system root to path (Unix) 
umask ( mask) -> int: set current numeric umask and return previous one 
ctermid () -* str: filename of controlling terminal (Unix) 
getlogin () -* str: name of user logged on controlling terminal (Unix) 
User, process, group IDs 
| pid\ process id, gid: group id, uid: user id 
getpid () -> int: current pid 
getegid () -* int: effective gid (Unix) 
setegid (egid) > set process effective gid (Unix) 
geteuid () -* int: effective uid (Unix) 
seteuid (eu/d) >■ set process effective uid (Unix) 
getgid () -> int: real gid (Unix) 
setgid (gid) *■ set process gid (Unix) 
getuid() -> int: current process' uid (Unix) 
setuid (uid) *■ set process current uid (Unix) 
setregid (rgid, egid) ► set process real and effective gid (Unix) 
setreuid (ruid,euid) > set process real and effective uid (Unix) 


getpgrp ()-> int: current gid (Unix) 

getgroups () -> [int]: list of supplemental associated gid (Unix) 
setgroups (groups) > set list of supplemental associated gid (Unix) 
setpgrp () ► call System function 1 (Unix) 
getppid () -» int: parenfs pid (Unix) 
setsid() > call system function 1 (Unix) 

getpgid (pid) -> int: process group id of process id pid (0=current) (Unix) 

getsid (pid) > call system function 1 (Unix) 

setpgid (pid,pgrp) > set process pid group to pgrp 1 (Unix) 

| 1 See manual for semantics. 

Timings, Priority 

times ()-> (ut,st,cut,cst,ert): (float_delay{5>): usertime, system time, 
children's user time, chiidren's system time, elapsed real time 
nice ( increment) -* int: renice process - return new niceness (Unix) 

Memory 

plock (op) > lock program segments into memory - see <sys/lock.h> for 
op values (Unix) 

Host Informations 

strerror ( code) -> str: error message for the error code 
uname () -> tuple: current operating system Identification, (sysname, 
nodename, release, version, machine) (recent Unix) 
sys. byteorder -> str: host native byte order big or little 
sys. winver -» str: version numberfor registry keys (Windows) 
sys. platform -» str: platform identifier (ex. linux2) 

Following data are in os and in os.path. 

defpath -> str: search path for os . exec*p* () and os . spawn*p* () if 
environment PATFI not defined 
linesep -> str: end of line char(s) for the plaftorm 
devnull -* str: file path of null device 

Python Informations 

sys . builtin_module_names -» (str): names of modules compiled into 
interpreter 

sys. Copyright -> str: Copyright of interpreter 
sys. hexversion -> int: Python version with one digit by byte 
sys. version -> str: interpreter version + build + compiler 
sys. dllhandle -> int: handle of Python DLL (Windows) 
sys. executable -> str: name of interpreter executable binary 
sys .prefix -* str: directory prefix for platform independant Python files 
sys . api_version -* int: version of Python C API 
sys. version_info -» (int{3}, str ,int): (major, minor, micro, 
releaselevel, serial) - release in alpha, beta, candidate, final 
Signal Handling 

Standard module signal. See doc for general rules about signals 
usage in Python. 

Signal handlers are callable f (signainum,stackframe). 

alarm (time) -> float_delay: previous alarm remaining time - request a new 
SIGALRM in time seconds - cancel previous one - time*0 (Unix) 
alarm(O) -> float_delay: previous alarm remaining time - cancel previous 
alarm (Unix) 

getsignal ( signainum) -> fct: current signal handler or SIG IGN or SIGDFL 
or None (handler not installed from Python) 
pause () >• sleep process until a signal is received (Unix) 
signal (signainum, handler) -> fct: previous handler for signal (as 
getsignal) - install new handler (maybe SIGJGN or SIG_DFL too) - only 
callable in main thread 
Following signal constants are defined : 
sig_dfl -v 0: default signal handler function 
sig_ign -> 1: ignore signal handler function 
nsig -> int: highest signal number +1 

Module also defines signal numbers (Posix examples - runtime 
definition is platform dependant) : 

14b 


sighup terminal or control processus disconnection 

sigint keyboard interrupt 

sigquit quit request from keyboard 

sigill illegal instruction 

sigabrt abort stop signal 

sigfpe floating point error 

sigkill the KILL signal 

sigsegv invalid memory reference 

sigpipe pipe write without reader 

sigalrm alarm timer elapsed 

sigterm termination signal 

sigusrI user signal 1 

SIGUSR2 user signal 2 

sigchld terminated/stopped child 

sigcont continue process (if stopped) 

sigstop stop process 

sigtstp stop request from keyboard 

sigttin read on tty while in background 

sigttou write on tty while in background 

see your platform documentation (man 7 signal on Linux). 
Functions to send signals are in os module : 
kill (pid,sig) > kill process pid with signal sig (Unix) 
killpg (pgid,sig) > kill process group pgid with signal sig (Unix) 

Simple Externa! Process Control 
Use Standard module subprocess. It wraps external process 
creation and control in Popen objects. Child process exceptions 
raised before execution are re-raised in parent process, exceptions 
will have child_traceback attribute (string). 

Note : subprocess tools will never call /bin/sh implicitly. 
pipe -> -l: constant value used for Popen stdin stdout stderr params 
call (*args,**kwargs)-> int: run command with arguments, waitfor 
completion, return retcode - convenient wrapper around Popen object 
Use Popen objects as process control tools : 

P = 

Popen (args, bufsize= 0, executable=None ,stdin=None, stdout= None , 
stde/r=None ,preexec_fn=None, close_fds=False, sbe//=False, cwd=N 

one , 

env=None , universal_newlines=False ,startupinfo=None, creationflags= 
0 ) 

args is a string/list of strings [ "command", "argl", "arg2",...] 
bufsize like for file/open functions 
executable can be used to provide command in place of 
args [0] 

stdin, stdout and stderr can be pipe to capture file and 
communicate with subprocess 

preexecjn is called just before child process execution 
closejds bool force subprocess inherited files to be closed, 
except 0 1 and 2 

Shell bool force execution of command throught the Shell 
cwd string specify working directory to set for subprocess start 
env dictionnary specify environment variables for subprocess 
universal_newlines translate all newlines to \n (like u mode for 
files) 

startupinfo and creationftags are optional informations for 
process creation under Windows 

p . poli () -* int/None: check child process termination, return returncode 
attribute 

p.wait () -* int: wait for child process to terminate, return returncode 
attribute 

p. communicate (input=None) -> (stdout,stderr): send data (input 
string)to stdin, read data from stdout/stderr until end-of-file, wait process 
to terminate, return read values - data read is buffered in memory 
p . stdin -> f ile/None: Standard input from chil process if captured 
p. stdout-* f ile/None: Standard outputfrom chil process if captured 
p. stderr -> f ile/None: error output from chil process if captured 
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p.pid -> int: process ID of child process 

p. returncode -> int/None: child process return code (None if not 
terminated) - on Unix -N for subprocess terminated by signal N 
I Use subprocess module when possible (cleaner, simpler interface, 

| see docs for examples). See also external module pexpect 

Advanced External Process Control 

See following functions from os module. 

execl (path , largi ,]) 

execle (path, [arg[, env) 

execip (file, largi , ...]]) 

execlpe (file,largien v) 

execv (path ,args) 

execve (path, args, env) 

execvp (file, args) 

execvpe (file,args,env) 

With exec... new program replace current process (fct don't return). 
'p' versions use PATH to locate executable file, 'e' versions use a 
dict env to setup new program environment. '1' versions use a 
positioned arg, 'v' versions use list of variable args. 
spawnl (mode,path, [argl ,...]]) —» int 
spawnl e (mode,path, largienv) -> int 
spawnlp (mode, file, largi, J ]) -* int 
spawnlpe (mode, file, largi , env) -> int 
spawn v (mode,path,args) -> int 
spawn ve (mode,path, args, env) -» int 
spawnvp (mode, file,args) -> int 
spawnvp e (mode, file, args, env) -» int 

With spawn... new process is created. 'Ipev' versions like for exec... 

If mode is p_nowait or p_nowaitO, return child pid (Unix) or process 
handle (Windows). If mode is p_wait, wait child termination and 
return its exit code (>0) or its killing signal (<0). On Windows 
mode can be, p_detach (same as p_nowait but new process 
detached from calling process console) or p_overlay (current 
process is replaced). 

fork () -> pid: fork a child process, return 0 in child, child pid in parent 
(Unix) 

forkpty () -> (int{2}): (pid.fd): fork using new pseudo-terminal for child - 
pid is o in child, child pid in parent - fd pseudo-terminal master end (Unix) 
startfile (path) > open file path as if double-clicked in explorer 
(Windows) 

system (cmd)-> value: execute string cmd in subshell - generally return 
(pid/status) (Unix) or status (Windows) 

wait () -* (int{2}): (pid,status) wait completion of a child process (Unix) 

- status=OxZZTT where zz=exit code, TT=signal num 
waitpid (pid,options )-* (int{2}>: (pid,status) (Unix): 
pid>0 wait for specific process, 
pid=0 wait for any child in process group, 
pid=-l wait for any child of current process, 
pid<-l wait for any process in process group -pid 
option in WNOHANG, WCONTINUED, WUNTRACED 
status=OxZZTT where zz=exit code, TT=signal num 
waitpid (pid, options) -* (int{2}>: (pid,status) (Windows): pid is any 
process handle (>0) - option ignored - status=0xzz00 where zz=exit 
code 

Status informations extraction 

wcoredump (status) -> bool: test process generated core-dump (Unix) 
wifcontinued (status) -» bool: test process continued from a job control 
stop (Unix) 

wifstopped (status) -» bool: test process stopped (Unix) 
wifsignaled (status) -> bool: test exited on signal (Unix) 
wifexited (status) -> bool: test process exited via exit(2) system call 
(Unix) 

wexitstatus (status) -> int: if exited via exit(2), return exit parameter 
(Unix) 


wstopsig ( status)-* int: signal having stopped process (Unix) 
wtermsig ( status)-* int: signal having exited process (Unix) 

Pipes On Process 

Three functions available in popen2 module (and in os module 
where stdin/stdout return values are inverted). 
popen2 (cmdl ,bufsizel ,mode]]) -* (file{2}): (stdout.stdin): execute 
cmd as sub-process 

popen3 (cmdl,bufsizel ,mode]]) -> (file{3}): (stdout.stdin,stderr): 
execute cmd as sub-process 

popen4 (cmdl,bufsizel,mode]]) ^ (file{2}): stdout_stderr,stdin): 
execute cmd as sub-process 

Where bufsize is buffer size for l/O pipes, and mode is 'b' (binary 
streams) or 't' (text streams, default). Param cmd is a string 
passed to os. system - on Unix it can be a sequence of strings 
passed directly to the program without Shell intervention. 

On Unix, popen2 module also defines Popen3 class (used in popen2 
and popen3 functions) and Popen4 class (used in popen4 function) : 
Popen3 (cmdl,capturestderrl,bufsize]]) -> Popen3: cmd : str Shell 
command, captudestderr. bool (default False) 

Popen4 (cmdl, bufsize])-» Popen4 

Popen3 and Popen4 objects have following attributes : 
p . poli () -* int: child return code or -l if child not terminated 
p . wait () -> int: child return code 

p. fromchild -> file: output from child (stdout and stderr for Popen4) 
p. toohild -» file: input to child 

p. childerr -» file: error output from child if requested else None (None 

for Popen4) 

p . pid -* int: child process pid 
See also module commands (Unix). 

XML Processing 

Several modules to process XML are available. Some with Standard 
SAX and DOM interfaces, others with more Pythonic interfaces. 

See also third party PyXML extension package. 

SAX - Event-driven 

Base functions in xml. sax module. 

make_parser (Iparserjist]) -> XMLReader: built from first parser 
available 

parse (filename_or_stream, content_handlerl, error_handler]) y parse 
document using first parser available 

parseString (string,content_handlerl, error_hand!er]) > parse string 
using first parser available 

XMLReader Interface 
Defined in xml . sax. xmlreader. 
p = xml. sax .make_parser () -> XMLReader object 
p. parse (source) y completly parse source - source is filename or URL or 
file-like or InputSource- input byte streams (not character streams) 
p . getContentHandler () -> ContentHandler: current One 
p. setContentHandler (handler) y set current content handler 
p . getDTDHandler () -> DTDHandler: Current One 
p. setDTDHandler (handler) y set current DTD handler 
p . getEntityResolver () -* EntityResolver: current One 
p. setEntityResolver (handler) y set current entity resolver 
p . getErrorHandler () -> ErrorHandler: current One 
p. setErrorHandler (handler) > set current error handler 
p. setLocale (locale) > set locale for errors and warnings 
p.getFeature ( featurename) -> current settings for feature 1 
p. setFeature (featurename, value) > set feature to value 
p. getProperty (propertyname) -» current settings for property 2 
p. setProperty (propertyname, value) y set property to value 
There is also an incrementalParser subclass interface with : 
p.feed(data) y process a chunk of data 

p. close () >• assume end of document, check well-formedness, cleanup 

15b 


p . reset () > after close, prepare new parsing 

1 Feature names in xml sax handler as feature_xxx. 

2 Property names in xml sax handler as property_xxx 

InputSource Interface 

Provide source of data for parser. 
isrc. setPublicid(/c() >• set public identifier 
isrc. getPublicld() -> Unicode: public identifier 
isrc. setSystemid (id) > set system identifier 
isrc. getSystemld() -> Unicode: system identifier 
isrc. setEncoding (encoding) > set encoding - must be a string 
acceptable for an XML encoding declaration - ignored if InputSource 
contains character stream 
isrc . getEncoding () -> str/None (if unknown) 
isrc. setByteStream (bytefi/e) > set input byte stream - ignored if 
InputSource contains character stream 
isrc. getByteStream() -> byte stream 

isrc. se tchar ac ter stream (charfile) y set character (Unicode) stream 
isrc. getCharacterStreamO -> character stream 
Locator Interface 

Instances of Locator provide these methods: 
loc. getColumnNumber () -> int: column number where current event 
ends 

loc. getLineNumber () -» int: line number where current event ends 
loc. getPublicid () -> str: public identifier of current event 
loc. getSystemid() -> str: system identifier of current event 
Attributes Interface 

Also implement parts mapping protocol (copy (), get (), has_key (), 
items (), keys (), and values ()). 
ai. getLength () -> int: number of attributes 
ai. getNames () -> [Unicode]: names of attributes 
ai. getType (name) -> type of attribute name - normally 'cdata' 
ai . getvalue (name)-* Unicode: value of attribute name 
AttributesNS Interface 
Also implement Attributes interface. 

ansi. getValueByQName (name) -> Unicode: value of attribute qualified 
name 

ansi. getNameByQName (name) -> (unicode{2}): (namespace, localname) 
for qualified name 

ansi . getQNameByName (namepair )-> Unicode: qualified name for 
(namespace, localname) 

ansi . getQNames () -> [Unicode]: qualified names of all attributes 
ContentHandler Interface 

Defined in xml.sax.handler. Its methods are handlers called when 
parser find XML structures. 

ch = MyContentHandler () -> ContentHandler subclass object 
efi.setDocumentLocator (locator) > set locator for origin of document 
events 

cfi.startDocument () ► beginning of document 
ch . endDocument () >• end of document 

cfi.startPrefixMapping (prefix,uri) y begin of a prefix-URI namespace 
mapping - see doc 

ch . endPrefixMapping (prefix) > end of a prefix-URI namespace mapping 
ch . startElement (name, attrs) y start of an element - non-namespace 
mode - attrs has an Attributes interface (may be reused - copy data) 
ch.endElement (name) > end of an element - non-namespace mode 
ch . startElementNS (name ,qname, attrs) y start of an element- 
namespace mode - name is (uri,localname) - qname is raw XML name - 
attrs has an AttributesNS interface (may be reused - copy data) - 
qname may be None (upon feature_namespace_prefixes) 
cb.endElementNS (name, qname) y end of an element - namespace 
mode 

ch. charae ter s (content) > character data - content is str or Unicode 

15c 


15a 

















ch.ignorableWhitespace (whitespace) > whitespaces 
ch . processinginstruction (target,data) > Processing instructiori 
cti.skippedEntity (name) > entity not processed 
DTDHandler Interface 

Defined in xml.sax.handler. Its methods are handlers called when 
parser need DTD relative work. 
dh = MyDTDHandler () -> DTDHandler subclass object 
dh. notationDecl (name,publicld,systemld) > notation declaration 
dh . unparsedEntityDecl (name, publicld, systemld , ndata) > unparsed 
entity declaration 

EntityResolver Interface 

Defined in xml.sax.handler. Its methods are handlers called when 
parser need external entity resolution. 

er = MyEntityResolver () -* EntityResolver interface object 
er. resolveEntity (publicld,systemld) -> str/inputSource: default 
return systemld 
Exceptions 

Defined in xml. sax module. 

SAXException (msg[ ,except/on]) 

SAXParseException (msg, exception Jocator) — invalid XML 

SAXNotRecognizedException ( msg[, exception ]) 
SAXNotSupportedException (msg[ , exception]) 

ErrorHandler Interface 

Defined in xml.sax.handler. Its methods are handlers called when 
parser detect an error. Their exception parameters get 

SAXParseException objects. 

eh = MyErroHandler () -> ErrorHandler interface object 
eh .error (exception) > recovererable error - parsing will continue if 
method return 

eh. fatalError ( exception) > unrecoverable error - parsing must stop 
eh .warning (exception) *■ minor warning - parsing will continue if method 
return 

SAX Utilities 

Defined in xml.sax.saxutils. 

escape (data[,entities]) -> str: s < > escaped - escape other entities 
replacing mapping strings (keys) by corresponding identifiers 
unescape (cfataj r entities]) -> str: samp; sit; sgt; unescaped - 
unescape other entities replacing mapping identifiers (keys) by 
corresponding strings 

quoteattr (data[, entities]) -> str: as escape + quote string to be used 
as attribute value 

prepare_input_source (source] ,base]) -> InputSource: SOUrce is 
string, f ile-like, or InputSource - base is an URL string - return 

InputSource for parser 

Class XMLGenerator is a ContentHandler writing SAX events into 
an XML document (ie. reproduce original document). 

XMLGenerator ([out[ ,encod/ng]]) -> content handler: out file-like, deault 
to sys.stdout - encoding default to ' iso-8859-l ' 

Class XMLFilterBase is a default pass-throught events, can be 
subclassed to modify events on-fly before their Processing by 
application handlers. 

XMLFilterBase (base) -* events filter 

Features & Properties 

Defined in xml. sax.handler. Dont give their value, but their 
meaning. 

feature_namespaces‘ -> True: perform namespace Processing. False: 
no namespace Processing (so no namespace prefixes). 
feature_namespace_prefixes 1 -* True: report original prefixed names 
and attributes used for namespace declarations. 
feature_string_interning 1 -* True: intern ali names (elements, 
prefixes, attributes, namespace URIs, local names). 


feature-Validation 1 -* True: report ali validation errors. 
feature_external_ges 1 -» True: include all external general (text) 
entities. 

feature_external_pes 1 -> True: include all external parameter entities, 
including the external DTD subset. 
all_features -> list of all features 

property_lexical_handler -» optional extension handler for lexical 
events (like comments). 

property_declaration_handler -> optional extension handler for DTD- 
related events other than notations and unparsed entities. 
property_dom_node 1 -» visited DOM node (if DOM iterator) when parsing, 
else root DOM node. 

property_xml_string -> literal string source of current event (read only 
property). 

all_properties -> list of all properties names 
| 1 can only be read during parsing (and modified before). 

DOM - In-memory Tree 

Defined in xml.dom. Two function to register/access DOM 
processors, and some constants. 

registerDOMImplementation (name, factory) *■ register DOM 
implementation factory 

getDOMimplementation ([name[,features]]) -» DOM implementation - 
name may be None - may found name in env. var PYTHON_DOM - features 
is [(featurename.version),...] 

empty_namespace -> no namespace associated with a node 
xml_namespace -> xml prefix namespace 

xmlns_namespace -> namespace URI for namespace declarations - DOM 
level 2 specification definition 

XHTML_NAMESPACE -> URI of XHTML namespace (XHTML 1.0) 
DOMImplementation 

impl. hasFeature (feature,version) -» bool: test for supported feature in 
an implementation 
Node 

Defined in xml.dom, class Node is parent of XML components nodes 
classes. 

O . nodeType -> int: (ro) in ELEMENT_NODE, ATTRIBUTE_NODE, 
TEXT_NODE, CDATA_SECTION_NODE, ENTITY_NODE, 
PROCESSING_INSTRUCTION_NODE, COMMENT_NODE, DOCUMENT_NODE, 
DOCUMENT_TYPE_NODE, NOTATION_NODE 
o.parentNode -» Node/None: (ro) - None for Attr nodes 
o. attributes -> NamedNodeMap/None: attribute objects for elements, 
else None 

o . previousSibling -> Node/None: (ro) previous node in parenfs children 
o. nextSibling -> Node/None: (ro) next node in parenfs children 
o . childNodes -> [Node]: (ro) list of subnodes 
o. firstChild -> Node/None: (ro) first subnode 
o . lastchild -> Node/None: (ro) last subnode 

o . localName -* unicode/None: (ro) element name without namespace 
prefix 

o. prefix -> unicode/None: (ro) element namespace prefix - may be 
empty string or None 

o . namespaceURl -> unicode/None: (ro) URI associated to element 
namespace 

o . nodeName -> unicode/None: (ro) usage specified in subclasses 
o . nodeValue -> unicode/None: (ro) usage specified in subclasses 
o . hasAttributes () -* bool: test any attribute existence 
o . hasChildNodes () -* bool: test any subnode existence 
o. isSameNode (other) -> bool: test other refers same node 
o. appendChild (newChild) -> new Child: add new child node at end of 
subnodes - return new child 

o . insertBefore (newChild, refChild) -> new Child: add new child node 
before an existing subnode - at end of subnodes if refChild is None - return 
new child 

o. removeChild (oldChild) -> oldChild: remove a subnode, return it - when 


no longer used, must call oldChild. unlink() 

o. replaceChild (newChild, oldChild) *■ replace existing subnode with a 
new one 

o. normalize () ► join adjacent text nodes 

o. cloneNode (deep) -> Node: if deep, clone subnodes too - return clone 
NodeList 

A sequence of nodes, usable as a Python sequence (maybe 
modifiable upon implementation). 
o. length -> int: number of nodes in the sequence 
o. item (/) -» Node/None: i th item in the list 
DocumentType 
Subclass of Node. 

O. nodeType -> DOCUMENT_TYPE_NODE 

o. publicld -> unicode/None: public identifier for external subset of DTD 
o. systemld -> unicode/None: System identifier URI for external subset of 
DTD 

o . internalSubset -> unicode/None: complete internal subset from the 
document - without brackets 

o . name -> unicode/None: name of root element (as given in DOCTYPE) 
o. entities -> NamedNodeMap/None: definition of external entities 
o. notations -* NamedNodeMap/None: definition of notations 
Document 
Subclass of Node. 

0. nodeType -> DOCUMENT_NODE 

o . documentElement -» Element: root element of the document 
o. createElement (tagName) -> Element: new 1 element node 
o. createElementNS (namespaceURl,tagName) -> Element: new 1 
element node with namespace - tagName may have prefix 
o . createTextNode (data) -> Element: new 1 text node containing data 
o . createComment (data) -> Element: new 1 comment node containing 
data 

0. createProcessinglnstruction (target , data) -a Element: new 1 
Processing instruction node containing target and data 
o. createAttribute (name) -> Element: new 1 attribute node 
o. createAttributeNS (namespaceURl,qualifiedName) -> Element: 
new 1 attribute node with namespace - tagName may have prefix 
0. getElementsByTagName ( tagName) -* NodeList: search for all 
descendants (deep search) having type tagName 

0 . getElementsByTagNameNS (namespaceURl, localName) -> NodeList: 
search for all descendants (deep search) having namespaceURl and 
localName (part after prefix) 

1 New nodes are standalone - you must insert/associate them in/to 
document parts. 

Element 

Subclass of Node. 

0 . nodeType -* ELEMENT_NODE 

o. tagName -> Unicode: element type name - with namespace may contain 
colons 

0. getElementsByTagName (tagName) -* NodeList: search for all 
descendants (deep search) having type tagName 

o. getElementsByTagNameNS (namespaceURl,localName) -> NodeList: 
search for all descendants (deep search) having namespaceURl and 
localName (part after prefix) 

o.getAttribute (attname) -> Unicode: attribute value 
o. getAttributeNode (attrname) -» Attr: attribute node 
o. getAttributeNS(namespaceL/R/ , localName) -* Unicode: attribute 
value 

o.getAttributeNodeNS (namespaceURl,localName )-* Attr: attribute 
node 

o. removeAttribute (attname) *■ remove attribute by name - ignore 
missing attribute 

o. removeAttributeNode (oldAttr) -> Attr: remove and return oldAttr 
o . removeAttributeNS (namespaceURl, localName) > remove attribute 
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by namespace URI and name - ignore missing attribute 
o. setAttribute (attname, value) > set attribute string value 
o. setAttributeNode ( newAttr ) -> Attr: set attribute from a new Attr 
node - return old one 

o. setAttributeNodeNS ( newAttr) -> Attr: set attribute from a new Attr 
node with namespace URI and local name - return old one 
o. setAttributeNS (namespaceURI ,qname, value) -> Attr: set attribute 
string value from a namespaceURI and qname (whole attribute name) - 
return old one 
Attr 

Subclass of Node. 

O . nodeType -> ATTRIBUTE_NODE 

o. name -> Unicode: (ro) attribute full name - may have colons 
o. localName -> Unicode: (ro) attribute name - part after colons 
o.prefix -* Unicode: (ro) attribute prefix - part before colons - may be 
empty 

NamedNodeMap 

A mapping of nodes - experimentally usable as a Python mapping. 
o. length -» int: length of attributes list 

o. item (index) -> Attr: attribute at index - arbitrary but consistent order 
Comment 

Subclass of Node. Cannot have subnode. 

0 . nodeType -> COMMENT_NODE 

o. data -> Unicode: content of the comment, without < ! — and — > 

Text 

Subclasses of Node. Cannot have subnode. Text part in an element. 

0 . nodeType -> TEXT_NODE 
o. data -> Unicode: text content 
CDATASection 

Subclasses of Node. Cannot have subnode. CDATA section in a 
document, may have multiple CDATASection nodes for one CDATA. 
0 . nodeType -> CDATA_SECTION_NODE 
0 . data -* Unicode: CDATA content 

Processinglnstruction 

Subclasses of Node. Cannot have subnode. Represents a Processing 
instruction in the XML document: this inherits from the Node 
interface and cannot have child nodes. 

0 . nodeType -> PROCESSING_INSTRUCTION_NODE 
o. target -* Unicode: (ro) Processing instruction content up to first 
whitespace 

o . data -> Unicode: (ro) Processing instruction content after first 
whitespace 


Exceptions 

Python map DOM error codes to exceptions. 


DOM codes constants 

Exception 

DOMSTRING SIZE ERR 

DomstringSizeErr 

HIERARCHY REQUEST ERR 

HierarchyRequestErr 

INDEX SIZE ERR 

IndexSizeErr 

INUSE ATTRIBUTE ERR 

InuseAttributeErr 

INVALID ACCESS ERR 

InvalidAccessErr 

INVALID CHARACTER ERR 

InvalidCharacterErr 

INVALID MODIFICATION ERR 

InvalidModificationErr 

INVALID STATE ERR 

InvalidStateErr 

NAMESPACE ERR 

NamespaceErr 

NOT FOUND ERR 

NotFoundErr 

NOT SUPPORTED ERR 

NotSupportedErr 

NO DATA ALLOWED ERR 

NoDataAllowedErr 

NO MODIFICATION ALLOWED ERR 

NoModificationAllowedErr 

SYNTAX ERR 

SyntaxErr 

WRONG_DOCUMENT ERR 

WrongDocumentErr 


exception. code -> int: DOM code corresponding to exception 


exception. msg -> string: message for exception 

DOMException 

DomstringSizeErr — implementation limit reach 
HierarchyRequestErr — insert at wrong place 
indexSizeErr — index range error 
inuseAttributeErr — Attr node already used in tree 
invalidAccessErr — param/operation unsupported by object 
InvalidCharacterErr — character invalid in the context 
invalidModificationErr — can't modify node type 
invalidStateErr — try to use an undefined/unusable object 
NamespaceErr — change forbidden in namespace context 
NotFoundErr — node don't exist in referenced context 
NotSupportedErr — operation/type unsupported by 
implementation 

NoDataAllowedErr — no data for this node 

NoModificationAllowedErr — can't modify object 
SyntaxErr — invalide/illegal string 

WrongDocumentErr — impl. can't migrate nodes between docs 

Databases 

See Python.org wiki for a list of database interface modules. 

Some interfaces are for external DB engines (MySQL, PostgreSQL, 
BerkeleyDB, SQLite, Metakit...), otherfor pure Python DB engines 
(gadfly, ZODB, KirkyBase, Buzhug...). 

Ceneric access to DBM-style DBs 
Standard module anydbm is a front-end to some available DB 
modules : dbhash (->bsddb-»Berkeley DB), gdbm (->GNU dbm), dbm 
(->unix dbm) and the slow portable fallback dumbdbm. 

Data stored in DBM-style files are accessed via a dictionary-like 
interface where keys and values must be str. 
open (filenamel ,flag[ ,mode]]) -> dictionary-like object: flag in 'r' (read- 
default), 'w' (write), ' c' (create if doesn't exist), 'n' (create new empty) 
- mode is unix mode flags for creation 

error -> tuple of exception classes from DB modules (anydbm.error,...) 
Uses module whichdb to identify right DB module for existing file. 
For new files, use first available DB module in the order of the list. 
This is used by shelve module (see Persistence, pl2). 

DB modules can have specific functions related to their backend, 
see docs. 

Standard DB API for SQL databases 

Generally modules for SQL databases use the Standard Python 
Database API v2 (defined in PEP249). 


API Informations 

apilevel -> str: currently ' l . 0 ' or '2.0' - ' l. 0 ' if undefined 
threadsafety -> int: level of thread safety 


# 

share module 

share connections 

share cursors 

0 

no 

no 

no 

1 

yes 

no 

no 

2 

yes 

yes 

no 

3 

yes 

yes 

yes 


paramstyle -> str: parameter marker for requests 


value 

params 

example 

' qmark ' 

Question mark style 1 

...WHERE name=? 

' numeric ' 

Numeric, positional style 1 or2 

...WHERE name=:l 

' named ' 

Named style 2 

...WHERE name=:name 

' format ' 

ANSI C printf format codes 1 

...WHERE name=%s 

' pyformat 

Python extended format codes 2 

...WHERE name=%(name)s 


1 Parameters as positional values in a sequence. 

2 Parameters as named values in a map. 


Exceptions 

(StandardError) 

Warning — important warning 
Error — a catch ali 


interfaceError — problem with interface (not database) 

DatabaseError 

DataError — problem with data Processing 

OperationalError — problem during database operations 

IntegrityError 

InternalError 

ProgrammingError — SQL programming related error 

NotSupportedError 

Exceptions classes may also be available as Connection objects 
attributes (optional). 

Connection 

connect (dsn[, user[, password[ ,host[, database ]]]]) -> Connection object 
(interface defined as a guideline) - dsn=data source name string 
cx . errorhandler -* fct: (optional) handler for connection errors - 
errorhandler(connection, cursor/None, errorclass, errorvalue) - default 
handler fili cx.messages and may raise exceptions 
cx.messages -> [ (exception class,exception value) ]: (optional) 
messages received from database for operations with connection 
cx . close () ► terminate connection (may rollback if not commited) 
cx . commit () >■ commit pending transactions 
cx. rollback () >■ rollback pending transactions (optionnal) 

CX . cursor () -> new Cursor object 

Cursor 

CU . arraysize -* int: (RW) number of rows to fetch with fetchmany - 
default to 1 

cu . connection -> Connection: (optional) connection used by cursor 
cu. description -> [(name, type_code, display_size, internal_size, 
precision, scale, nuIl_ok) ] /None: describe resuit columns 
cu. errorhandler -» fct: (optional) handler for connection errors - 
errorhandler(connection, cursor, errorclass, errorvalue) - default handler 
fili cx.messages and may raise exceptions - inherited from connection 
cu . lastrowid -* int/None: (optional) row id of last modified column 
cu. messages -> [ (exception class,exception value) ]: (optional) 
messages received from database for operations with cursor 
cu.rowcount -* int: number of rows produced/affected by last request - 
-l or None if request eant touch rows 

cu. rownumber -» int/None: (optional) O-based index of the cursor in the 
resuit set if available 

cu.callproc (procnamei ,parameters]) -* (parameters) - (optional) call 
DB stored procedure - in resuit out and inout parameters may have been 
replaced by procedure 
cu. close () a close the cursor 

cu.exeeute (oper[ ,params ]) > prepare and exeeute DB request - 
params 1 is a sequence or a mapping (see module paramstyle variable) 
cu . exeeutemany (oper,params_seq) >• like exeeute, with a sequence of 
params (for multiple values) 

cu . fetehone ()-> (column_value,...) /None: next row of query resuit, 
None when no more data available 

cu. fetchmany ([s/ze]) -* [(column_value)j: next set of rows of query resuit, 
empty list when no more data available - size default to cu. arraysize 
cu . fetchall () -> [ (column_value) ]: ali remaining rows of query resuit, 
empty list when no more data available 

cu. next()-> (column_value) : (optional) next row of query resuit, raises 
stopiteration when no more data available 
cu. nextset () -> True/None: (optional) discards results up to next 
available set 

cu. scroll (value[ ,mode]) > (optional) - scroll cursor in current resuit set 
-mode is 'relative' (default) or 'absolute'. 

cu. setinputsizes ( sizes) > predefine memory areas for executexxx 
operations parameters - s/zes=[param_size,...] - param_size=Type Object 
or int (max length of a string param) - param_size=None for no 
predefinition 

cu.setoutputsize(s/ze[,co/umn]) > set column buffer size for fetehes 
of large columns (e.g. LONGs, BLOBs, etc.) by executexxx - column is 
index in resuit - ali columns if column not specified 
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cu . _iter_ () -» Cursor: (optional) object itself 

1 Method_ getitem _is used to get values in params, using 

position or name. Can use tuple or dict... or your own class 
objects with its_ getitem _ 

If next and _iter_ are defined, cursors are iterable. 

DB types Constructors 

Date ( year,month ,day)-> object to hold a date value 
iime(hour,minute ,second) -> object to hold a time value 
Timestamp (year, month, day, hour, minute, second) -> object to hold a 
time stamp value 

DateFromTicks ( ticks) -> object to hold a date value from a given ticks 
value 

TimeFromTicks (ticks) -> object to hold a time value from a given ticks 
value 

TimestampFromTicks ( ticks )-* object to hold a time stamp value from a 
given ticks value 

Binary ( string) -> object to hold a long binary string value 
SQL NULL values represented by Python None. 

DB types Typecodes 
string -> string-based column (CHAR) 
binary -> long binary column (LONG, RAW, BLOBs) 
number -> numeric column 
datetime -> date/time column 
ROWID -> row ID column (CHAR) 

Bulk 

Tools 

Batterles included: pdb (Python debugger), code bench with timeit 

(plO). 

A rnust have: pychecker. 

Take a look: pylint, psyco, pyrex, pycount, trace2html, 
depgraph, coverage, pycover, Pyflakes, pyreverse, HAP. 

Links 

Docs: http://www.python.org/doc/ 

FAQ Python: http://www.python.org/doc/faq/ 

PEPs: http://www.python.org/dev/peps/ (Python Enhancement 
Proposal) 

HOWTOs: http://www.amk.ca/python/howto/ 

Cookbook: http://aspn.activestate.com/ASPN/Python/Cookbook/ 

Dive Into: http://www.diveintopython.org/ 
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